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Changes in the 1.1 Release of Sun Windows 


This notice describes changes, deletions, and additions to SunWindows from release 1.0 to 
release 1.1. The main differences in 1.1 center around adding support for multiple screens and 
color displays. 

Sun Windows includes sources for window application programs in fusrftuntoolf*, the suntool 
library fuerjlibflibsvntooLa, the sunwindow library /uarllibJUbaunwindow.a, and the pixrect 
library / turl lib/lsbpixreet.a. For »untoola{l) user information, refer to the Uaer’a Manual for the 
Sun Workstation . For more detailed SunWindows programming information, refer to the refer¬ 
ence section of the Programmer’s Reference Manual for SunWindows . 


Upgrading from 1.0 to 1.1 SunWindows 
1.0 programs must be recompiled to run in 1.1. 


User Interface Differences — Changes to /usr/suntool/ 


Additions to the User Interface 

Additions to the user interface are: 
suntools 

Now takes an extensive argument list to control the environment of the window system. 
This includes indicating color, which screen, inversion, and so on. See OPTIONS in sun- 
tools(l) in the User’s Manual for the Sun Workstation for details. 

spheresdemo 

Now produces multiple colored spheres. A —g command line argument produces varying 
sha4es of gray spheres. These grays may not appear gray until the cursor is positioned in 
the window in which the spheres are being drawn. 

jumpdemo 

Now produces colored vectors. A -c command line argument causes the vectors to sparkle 
vis colormap rotation. 

System Fonts 

More fonts are available for use as the DEFAULTJ'ONT. See f uarf suntool}fizedwidthfonto{ * 
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and «unl 00 /s(l) in the Uatr't Manual for the Sun Workstation. 
Exiting suntools 

Typing followed by a 'Q to the Root Window exits suntools. 


New Programs 
adjaeentsereens{l) 

Tells the window system the physical relation of screens. 
locksereen{l) 

Puts a “lock” on and hides the current window context so logging out is no longer neces¬ 
sary. 

per/m 0 n(l) 

A graphic performance monitor. 


Suntool Library 

The changes to the suntool library involve several changes to the option subwindow interface, 
making the graphics subwindow more robust, and simplifying window management utilities. 


Option Subwindow Changes 

Three routines now take different arguments, return different values, and/or behave differently 
than they used to. These are: 

optfwjtezt 

Takes a fifth au'gument, the address of a notify procedure, exactly as for the other item- 
creation routines. The notify procedure is called whenever the value of the text item is 
changed, except by a call to optsw_Betvalue. It will be called with handles for the option 
subwindow and the item which changed. Optsw_getvalue should be used to actually retrieve 
the new value. This parameter to optswjtezt may be NULL to indicate "no notification.” 
optsw_getvtdue 

Behaves differently for text items; its second (destination) argument should now be a 
pointer to a struct stringjbuf, as defined in optionsw.h. This protects against the case where 
the value of the item is longer than the client’s buffer. In such a case, the buffer is filled, 
and the max count is returned; no terminating NULL is written in the client’s buffer. A sub¬ 
sequent call to optsw_getvatue for that item will return the next fragment, until the whole 
value has been reported. A terminating NULL is written in the buffer when there is room for 
it, and a subsequent call to ovtsw petvalue will start anew at the beginning of value. 
optsw_setplace 

Has had its arguments changed to be parallel with optsw_getplaee. It third argument is now 
a pointer to a struct item_plaee, instead of the struct rect pointer it used to take; the struct 
contains a rect, and four boolean bit flags indicating that a value is to be fixed for that 
item. 
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Option Subwindow Deletions 

The ftruet opt_item is no longer defined in a public header file. Routines which used to return a 
pointer to such a struct (all of the item-creation routines, for instance) now return an opaque 
pointer (caddr_t). Routines which took a pointer to such a struct as an argument now accept 
the opaque pointer. Inquiry and manipulation functions are provided to support access to the 
items without commitment to their internal representation. 


Option Subwindow Additions 

Two new structs are defined, one for ephw^etplaee and optsw_»etplaee, one for optsw_getvalue 
on text items: 
struct it€m_plaee 

Encodes the information about an item’s size and location which the client may see and 
modify. A pointer to such a struct is passed to optsw_getplaee (which fills it in) and 
optswjsetplace, which uses it to establish an item’s location, size, and willingness to change. 

struct stringjbuf 

Provides a counted buffer for text items' values to be stored into. Limit should be the size 
of t)ie buffer on a call to optsw_petvalue. 

The following new routines are also provided: 
optsw_setearet(o8w} 

Returns an item handle for the item which currently has the caret in osw, or NULL if there 
is no text item in osw. 
optsw_B€tceret(osw, ip) 

Makes the optionsw text item referred to by ip be the one which has the caret in the indi¬ 
cated optionsw. 
opts w_^ctfont(osw) 

Returns a pointer to the struct ptz/ont which is currently being used by the optionsw. 
optsw^tphee(osw, ip, place) 

Stores into the item_plaee struct pointed to by place a description of the size, position, and 
fixedness of the item indicated. 
optswjneztitemfosw, ip) 

Given an item in an optionsw, returns a handle for the next item in sequence. 
optsw^removeitems(osw, ip, count, reformat) 

Removes at most count items from osw, making them inaccessible to the user, but not des¬ 
troying them. 

optswjrestoreitemsfosw, ip, count, reformat) 

Restores at most count items in osw, starting at the item indicated by ip; returns the 
nun^ber restored. 

Graphic Sunwindow Changes 

Graphic sunwindow changes to the interface are: 


Revision D of 7 January 1984 


Changes-3 




Release 1.1 


SunWindo'ws Reference Manual 


gfx»w_tetinputma»k 

Should be called instead of win_tetinputmask. This call takes additional arguments as well. 


Graphic Sunwindow Deletions 

The graphics sunwindow procedure gfxBwjcUanxtp was removed from the interface because it is 
now obsolete due to the new implementation of the graphic subwindows. Graphics subwindows 
now use blanket windows instead of the old window takeover mechanism. You can instead call 
gfxtw_done, or do nothing at all, from SIOINT and SIQHUP handling routines. 


Graphic Sunwindow Additions 

Graphic sunwindow additions to the interface are: 
gfxtvt^catchsigwinch 

Catches and handles SIGWINCH. 

flfxtw_cateh»igMp 

Catches and handles SIGTSTP. 

gfxtw_^eatchaigeont 

Catches and handles SIQGONT. 
gfxaw_notutingmou$e 

May be called if your program doesn’t use the mouse; this is optional. 
gfxaw_inputmterrupta 

A substitute utility for tty process control while using the window input mechanism. 


Window Management Deletions 

Window management interface deletions include: 

Wmgr_changelevelonlj/ 

Removed in favor of the similar procedure vmgrjekangdevel. 

Wmgru^h angeatate 

Was removed in favor of the similar procedures wmgr_open and wmgr^cioae, 
Wmgr^aetupmenua 

Removed in favor of wmgr^aetupmenu. The interface no longer supports wmgr^rootmenu 
(moved into client code, see the auntooU.e source), thus, the change of plurality. 


Window Management Additions 

Window management additions to the interface are: 

wm^_open, tvmgr_eloae, wmgrjnove, wmgr_atreteh, wmgrjtop, wmgrjbottom, 

' tvtngr_refreahwindow Are the highest level window management routines and 
correspond exactly to tool menu operations. 
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umgr^ehangereet 

Provides finer control of moving and stretching user interaction. 
wmgr^confirm 

A standard confirmation utility. 
wmgr_handletooltnenuitem 

S'vritch to call top level 'window management routines based on tvmgr^toolmenu menu 
item chosen. 

wmgr_tetreetaUoc and ufmgr^etrectaUoc 

Global storage of next default window position. 


Sunwindow Library 

The changes to the suntool library center around keeping up with the pixrect library 
changes by providing a pixwin operation to match each pixrect operation and cleaning up 
the interface to screen structures. 


Changes to the Interface 

The screen struct wa?. completely overhauled to accommodate color and multiple screens. 
However, the scrjreet was left untouched and is the field that high level clients most often 
use. Therefore, no source changes should probably be required by most programs. 

Win_eereennew 

Now has a different calling sequence. It now takes a struct screen pointer and returns a 
window file descriptor. It used to take a window file descriptor and and struct screen 
pointer. 

Wm_«ereenpotiti0n9 

Was renamed win^^setgereenpositioM. 


Deletions from the Interface 

With the advent of blanket windows, using tpin_$etou!ner to temporarily change ownership 
of windows is no longer recommended. 


Additions to the Interface 

The pbcwin additions that correspond to the equivalent pixrect additions are: 
pwjregion 

Pixwin region operation. 
p\B_tttxt 

Pbcwin transparent text operation. 
pu)_j^atehrop 

I’ixwin batchrop operation. 
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ptBjiteneU 

Pixwin stencil operation. 

pw_putattributet and pw^etattributet 
Pixwin attributes control. 
pw_puteolormttp and pto^eteolormap 
Pixwin colormap control. 

The pixwin additions that extend pixrect functionality are: 

pw_jetem«tiame and puLff^fcnwnome 

Pixwin colormap segment name access. 

pw_prepare$urfttee 

Pixwin surface preparation (colormap segment related). 

pw_cyelecolormap 

Pixwin colormap utility. 

The pixwin font utilities that share the system font are: 

pw_pf»yaopen and pwjpftytclote 

Sharing of the default system font is provided. 

The screen-related additions are: 

win_gttacrecnpo»ition$ 

Retrieve neighbors of the window's screen. 

winjtetkbd and wmjittmt 

Change keyboard and mouse devices used by the screen. 
winjimtaereenfromargv 

Standard command line to screen specification parser. 

These are the additions related to the new blanket window mechanism: 
tvinjlnsertblanket 

Insert window into display tree and treat as a "blanket” window (one that always cov¬ 
ers its parent). 
u>in_r em o veblanket 

Remove blanket window from display tree. 
winjitblanket 

Check ‘is a window a blanket window?’ 


Pixrect Library 

Pixrects features a slightly modified interface to support color pbcrects. Also, the font for¬ 
mat and memory pixrect format has changed. 


Deletions from the Interface 

The create operation is removed from the pixrect operations vector. Pr_opett^ mem_create 
and prjregion define the available pixrect creation alternatives. 
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Changes to the Interface 

A ne^r frame buffer naming convention noir exists: 
fdev/fh 

The default frame buffer for a machine. This replaces f devfconaole which has other 
tty°related functions, and /dev/btcO v/lach no longer exists. 

Frame Buffer Naming Convention 

The general naming convention for a frame buffer follows the form / dev/ CTU in which: 
C is either “bw” (for monochrome displays) or “eg” (for color displays). 

T is the type of the display, such as “one” or “two” for Sun-1 or Sun-2 respectively. 

U is the unit number starting from 0, indicating which specific frame buffer. 

Some examples of frame buffer names are: / dev/bwoneO, /dev/bwtwoO and / dev/egoneO. 

The font format used in pfjtptn has been changed. The old format was in VAX byte order. 
The new format is in Motorola 68000 byte order (reversed from the VAX). You can tell if a 
font is in the new format by using the )ffe(l) program on the font file in question. The font 
file should be listed as “vfont definition”. The program «si»ap(l) converts a font file from 
the old format to the new. 

The structure format of mpr^data (the memory pixrect internal data format) has changed 
slightly. The Bint mrf_primary field has been split into short mdjprimary and short 
md^aga. The overall length of mprjdata remains the same. 


Additions to the Interface 
prjiteneil 

Provides spatial masking of the destination pixrect for control of the areas of the desti¬ 
nation pixrect to be painted by the source pixrect. 

prjpMteohrmixp and prjgetcolormap 

Provides a unified colormap and reversevideo interface for both color and monochrome 
pixreets. 

prjputaUributea and pr_ffefc«ri6«fcJ 

Provides access to a bitplane mask which specifies the modifiable bits in destination 
pixrect pixels. 

pfjltext 

Uses character bitmap as a stencil through which the specified color is squirted, hence 
background shows through around the characters. 
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Preface 


The Programmer’t Reference Manual for SunWtndowo provides primarily reference material on 
SunWindows, the Sun -window system. It is intended for programmers of applications using 
window system facilities. 


Manual Contents 

The contents of the manual are: 

Chapter 1 — Overview — Describes basic hardware and software support and the layers of 
implementation of SunWindows, the pizrect layer, the sanwindow layer, and the suntool layer. 

Chapter 2 ~ Pixel Data and Operationt —- Describes pixel data and operations in the lowest 
level output facilities of SunWindows, pixrects, pixrectops, memory pixrects, and text facilities 
for pixrects. 

Chapter 3 — Overlapped Windowt: Imaging Facilitied — Explains image generation on windows 
which may overlap other windows. 

Chapter 4 — Window Manipulation — Describes the aunwindow layer facilites for creating, posi¬ 
tioning, and controlling windows. 

Chapter 6 — Input to Application Programs — Discusses how user input is made available to 
application programs. 

Chapter i| — Suntool: Tools and Subwindows — Discusses how to write a tool, and covers crea¬ 
tion and- destruction of a tool and its subwindows, the strategy for dividing work among 
subwindowB, and the use of routines provided to accomplish that work. 

Chapter 7 — Suntool: Subwindow Packages — Discusses subwindows as building blocks in the 
construction of a tool, covers the currently existing subwindows, and suggests the approach for 
creating new kinds of subwindows. 

Chapter 8 — Suntool: User Interface Utilites Covers user interface utilities, the independent 
packages for use with the suntools environment, includes the actual window manipulation rou¬ 
tines used by tool windows, the icon facility, the selection manager, the fullscreen access 
mechanism, and menus and prompts. 

Appendix A — Rects and Rectlists — Describes the geometric structures used with the sunwin^ 
dow layer and provides a full description of the operations on these structures. 

Appendix B — Sample Tools — Provides an annotated collection of some simple tools to be 
used both as illustrations and as templates for client programmers; includes a graphics tool, a 
window pane tool, an option tool, and an icon tool. 

Appendix C — Sample Graphics Programs — Provides an annotated selection of several graph¬ 
ics programs for writing your own graphics programs; includes code for a bouncing ball 
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demonstration and for a “movie camera” program that displays files as frames from a movie. 

Note: The reference section of the Programmer's Reference Manual for SunWindows is neither a 
user guide nor an explanation of the internals of the window system. It presents the material in 
a bottom-up fashion with primitive concepts and facilities described first. It is not intended to 
be read linearly front-to-back; glance at the table of contents and the chapters on tools to get a 
general idea of how to use the rest of the material. 

The Vaer’s Manual for the Sun Workstation provides user information under «untoo/s(l) for 
SunWindows and under the appropriate entry for the particular application programs. The 
Beginner ’s Guide to the Sun Workstation provides a brief tutorial on general use of the mouse 
and the SunWindows pop-up mentis. 


A Note About Special Terms 

Several terms in this manual have meanings distinct from their common definitions or introduce 
concepts that are specific to programming in the SunWindows environment. We discuss the 
most important here. 

The word client indicates a program that uses window system facilities. This is in contrast to 
user, which refers to a human. 

Terms referring to display hardware, such as framebuffer, pixel, and rasterop, are used in well- 
established senses; novices who are confused should consult one of the standard texts, such as 
Fundamentals of Interactive Computer Graphics by J.D. Foley and A. Van Dam, Addison- 
Wesley, 1983. 

The position of the mouse is indicated by a cursor on the screen; this is any small image that 
moves about the screen in response to mouse motions. The term “cursor” is used elsewhere to 
indicate the location at which type-in will be inserted, or other editor functions performed. The 
two concepts are not often distinguished. To keep them distinct, we use the term caret to refer 
to the type-in location. 

A menu is a list of related choice items displayed on the screen in response to a user mouse- 
action. The user chooses one menu item by pointing at it with the cumor. Such menus are 
called transient or pop-up; they are displayed only while a mouse button is depressed, and are 
typically used for invoking parameterless operations. 

A rect is a structure that defines a rectangle. 

A rectliat is a structure that defines a list of recta. 

Up-down encoded keyboards are devices from which it is possible to receive two distinct signals 
when a key is pressed and then released. 

An icon is a small form of a window that typically displa]rs an identifying image rather than a 
portion of the window contents; it is frequently used for dormant application programs. For 
example, the default icon for a closed Shell Tool is a conch shell, representing the UNIX “C- 
Shell”. 

Note: The code examples show the proper case of letters for the names of macros, procedures, 
arguments, flags, and so on. The first letter in a sentence is capitalized as a courtesy to English, 
although the word may not then be technically correct. 










Chapter 1 


Overview 


1.1. What is SunWindows? 

SunWindo'ws is the Sun window system. It is a tool box and parts kit, not a closed, finished, end 
product. Its design emphasises extensibility, accessibility at multiple layers, and provision of 
appropriate parts and development tools. Specific applications are provided here both as exam¬ 
ples and because they are valuable for further development. The system is designed to be 
expanded by clients. 

The system is explicitly layered with interfaces at several levels for client programs. There is 
open access to lower levels, and also convenient and powerful facilities for common requirements 
at higher levels. For instance, it is always possible for a client to write directly to the screen, 
although in most circumstances it is preferable to employ higher-level routines. 


1.2. Hardware and Software Support 

The Sun Microsystems Workstation provides hardware and software support for the construc¬ 
tion of high-quality user interfaces. Hardware features include: 

• provision of a processor for each user, a prerequisite for powerful, responsive, cost-effective 
systems; 

• a bit-mapped display which allows arbitrary fonts and graphics to be used freely to make 
applications programs easier to learn and use; 

• hardware support of fast and convenient manipulation of image data; 

• a mouse pointing device for selecting operations from menus or for pointing at text, graph¬ 
ics and icons; and 

• an up-down encoded keyboard that supports sophisticated function-key interfaces at once 
simpler and more efficient than most command languages. 

Sun software is similarly structured to support high-quality interactions. The software features 

are: 

• a uniform interface to varied pixel-oriented devices that allows convenient incorporation of 
new devices into the system, and clean access to all these devices by application programs; 

• an extended device independence for input such as function keys and locators, to usei^ 
interface features; 

• a window management facility that keeps track of multiple overlapping windows, allowing 
their creation and rearrangement at will. The facility arbitrates screen access, detects des¬ 
tructive interactions such as overlapping, and initiates repairs. It also serializes and distri¬ 
butes user inputs to the multiple windows, allowing full type-ahead and mouse-ahead; and 
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• built on all these facilities, an executive and application environment that provides a system 
for running existing UNIX programs and new applications, taking advantage of icons, menus, 
prompts, mouse-driven selections, interprocess data exchange, a forms-oriented interface 
and useful cursor manipulations. 


1.3. Layers of Implementation 

There are three broad layers of SunWindows. These layers may be identified by the libraries 
that contain their implementations. The organization of the reference part of this manual 
reflects the three layers as described below. 

1. The pixrect level provides a device-independent interface to pixel operations. 

2. The tunwindow^ level implements a manager for overlapping windows, including imaging 
control, creation and manipulation of windows, and distribution of user inputs. 

3. The ttiniool level implements a multi-window executive and application environment. In its 
user interface, it includes a number of relatively independent packages, supporting, for 
instance, menus and selections. 


1.3.1. Pixrect Layer 

Chapter 2 describes the pixrect layer of the system. This level generalizes RasterOp display 
functions to arbitrary rectangles of pixels. Peculiarities of specific pixel-oriented devices, such 
as dimensions, addressing schemes, and pixel size and interpretation, are encapsulated in 
device-specific interfaces, which all present the same uniform interface to clients. 

The concept of a pixrect is quite general; it is convenient for referring to a whole display, as well 
as to the image of a single char 2 kcter in a font. It may also be used to describe the image which 
tracks the mouse. 

There is a balance between functionality and efficiency. All pixrects clip operations that extend 
beyond their boundaries. Since this may require substantial overhead, clients which can guaran¬ 
tee to stay within bounds may disable this feature. Where hardware support exists, it is taken 
advantage of without sacrificing generality: All pixrects support the same set of operations on 
their contents. 

These operations include general raster operations on rectangular areas, vectors, batch operar 
tions to handle common applications like text, and compact manipulation of constant or 
regularly-patterned data. A stencil operation provides spatial, two-dimension masking of the 
source pixrect with a mask pixrect to control the areas of the destination pixrect to be written. 

Color pixrects, as well as monochrome pixrects, are well supported. There are uniform opera¬ 
tions for accessing a pixrect’s eolormap. A colormap maps a pixel value to a screen color. The 
pixel planes affected by other operations can be controlled as well. Monochrome pixrects sup¬ 
port the same interface as color pixrects. Programs intended primarily for color pixrects usually 
produce reasonable images on monochrome pixrects, and vice versa. 


^ Note that the term ‘sunwindow’ refers to the layer or level of implementation while the word 
‘SunWindows’ is the name of the Sun window system. 
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1.3.2. Sunwindow Layer 

Cliapters 3 through S introduce windows and operations on them. A window is a rectangular 
display area, along with the process or processes responsible for its contents. This layer of the 
system maintains a database of windows which may overlap in both time and space. These win¬ 
dows may be nested, providing for distinct aubwindowt within an application’s screen space. 

Windows existing concurrently may all access a display; the window system provides locking 
primitives to guarantee that these accesses do not conflict. 

Arbitration between windows is also provided in the allocation of display space. Where one 
window limits the space available to another, it is necessary to provide clipping, so neither inter¬ 
feres with the other’s image. One such conflict handled by the sunmndow layer arises when 
windows share the same coordinates on the display: one overlaps the other. 

When one window impacts another window’s image without any action on the second window’s 
part, SunWindows informs the affected window of the damage it has suffered, and the areas 
that ought to be repaired. Windows may either recompute their contents for redisplay, or they 
may elect to have a full backup of their image in main memory, and merely copy the backup to 
the display when required. 

On color displays, colormap entries are a scarce resource. When shared among multiple applica¬ 
tions, they become even more scarce. Arbitration between windows is provided in the allocation 
of colormap entries. Provisions are made to share portions of the colormap. 

Windows may be created, destroyed, moved, stretched or shrunk, set at different levels in the 
overlapping structure, and otherwise manipulated. The sunwindow level of the system provides 
feicilities for performing all these operations. It also allows definition of the image which tracks 
the mouse while it is in the window, and inquiry and control over the mouse position. 

Separate collections of windows may reside on separate screens. The user interacts with these 
multiple screens with his single keyboard and mouse. 

User inputs are unified intb a single stream at this level, so that actions with the mouse and 
keyboard can be coordinated. This unified stream is then distributed to different windows, 
according to user or programmatic indications, ^^^ndows may be selective about which input 
events they will process, and rejected events will be offered to other windows for processing. 
This enables terminal-based programs to run within windows which will handle mouse interac¬ 
tions for them. 

1.3.3. Suntool Layer 

Chapters 6 through S of the reference part of this manual describe the suntool level of the sys¬ 
tem. While the first two layers provide client interfaces, the suntool level provides the user 
interface. 

We refer to an application program that is a client of this level of the window system as a tool. 
This term covers the one or more programs and processes which do the actual application pro¬ 
cessing. It also refers to the collection of windows through which the tool interacts with the 
user. This collection often includes a special icon, which is a small form the tool may take to be 
unobtrusive on the screen but still identifiable. Simple examples of tools may include a calcular 
tor, a bitmap editor, and a terminal emulator. Sun provides a few ready-built tools, several of 
which are illustrated in Appendix B. Customers are expected to develop their own tools to suit 
their specific needs. 
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SunWindows provides some common components of tools: 

• an executive framework that supplies the usual “main loop” of a program and coordinates 
the activities of the various subwindows; 

• a standard tool window that frames the active windows of the tool, identifying it with a 
name stripe at the top and borders around the subwindows. Each tool window has a facil¬ 
ity for manipulating itself in the overlapped window environment. This includes adjusting 
its size and position, including layering, and moving the boundaries between subwindows; 

• several commonly used tubwindow types that can be instantiated in the tool; 

• a standard scheme for laying out those subwindows; and 

• a facility that provides a default icon for the tool. 

The tuntools program initializes the window environment. It provides for: 

• automatic startup of a specified collection of tools; 

• dynamic invocation of standard tools; 

• management of the default window called the root window, which underlies all the tools; 
and 

• the user interface for leaving the window system. 

Users who wish some other form of environment management can replace the sunfooU program, 
while retaining the tools and supporting utilities. 

The facilities provided in the oantool library are relatively independent; they can be used with 
window contexts other than tuntooU. The icon facility mentioned above is in this category, as 
are the window manipulation facilities of ountooh. There is also a package for presenting menus 
to the user and interpreting the response. 
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This section discusses pixel data and operations in the lowest-level output facilities of SunWin- 
dows. These facilities will frequently be accessed indirectly, through higher-level abstractions 
described in chapters 3 through 8. However, some client implementors will deal at this level, for 
instance to include new display devices in the window system. The header file 
f usrf inetudelpixreetfpizrectjht.h includes the header files that you need to work at this level of 
the window system. It will also suffice to include Juarfincludeftuntoolftuntool_hd.h or 
j inrj include! avinwindowf tunwindow_ha.h. 


2.1. Pixrects 

The fundamental object of pixel manipulation in the window system is the pixrect. A pixrect 
encapsulates a rectangular array of pixels along with the operations which are defined on that 
data. Pixrects are designed along the model of objecta in an object-oriented programming sys¬ 
tem. They combine both data and operations, presenting their clients with a simple interface: a 
well-defined set of operations produces desired results, and details of representation and imple¬ 
mentation are hidden inside the object. 

The pixrect presents only its dimensions, a pointer to its operations, and a pointer to private 
data which those operations may use in performing their tasks. Further, the set of operations is 
the same across all pixrectS;, though of course their implementations must differ. This object- 
oriented style allows similar things which differ in small details to be gathered into a unified 
framework; it allows clients to use the same approach to all of them, and allows implementors 
to add new members or improve old ones without disturbing clients. 

Tte pixrect facility satisfies two broad objectives: 

• To provide a uniform interface to a variety of devicea for independence from device charac¬ 
teristics where they are irrelevant. Such characteristics include the actual device (pixrects 
may exist in memory and on printers as well as on displays), the dimensions and zkldressing 
schemes of the device, and the definition of the pixels, that is, how many bits in each, how 
they are aligned, and how interpreted. Color and monochrome devices use the same interface. 
Programs intended primarily for color pixrects usually produce reasonable images on mono¬ 
chrome pixrects, and vice versa. 

• To provide a proper balance of functionality and efficiency for a full range of pixel operations 
with performance close to that achieved by direct access to the hardware. Pixrect operations 
include generalised rasterops, vectors, text and other batch operations, compact manipulation 
of uniform and regularly-patterned data, as well as single-pixel reads and writes. All provide 
for clipping to the bounds of the rectangle if desired; this facility may be bypassed by clients 
which can perform it more efficiently themselves. A stencil function provides spatial masking 
of the source pixrect with a stencil pixrect to control the areas of the destination pixrect to 
be written. Where specialized hardware exists and can be used for a particular operation, it 
is, but not at the expense of violating the device-independent interface. 
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2.1.1. Pixels: Coordinates and Interpretation 

Pixels in a pixrect are addressed in two dimensions with the origin in the upper left comer, and 
X and y increasing to the right and down. The coordinates of a pixel in a pixrect are integers 
from 0 to the pixrect’s width or height minus 1. 

A pixrect is characterized by a depth, the number of bits required to hold one pixel. A large 
class of displays uses a single bit to select black or white (or green or orange, depending on the 
display technology). On these monoehrome displays and in memory pixrects one bit deep, a 1 
indicates foreground and a 0 background. No further Interpretation is applied to memory. The 
default interpretation on Sun displays is a white background and a black foreground. 

Other displays use several bits to identify a color or gray level. Typically, though not neces¬ 
sarily, the pixel value is used as an index into a eolormap, where colors may be deBned with 
higher precision than in the pixel. A common arrangement is to use an 8-bit pixel to choose one 
of 256 colors, each of which is defined in 24 bits, 8 each of red, green and blue. Pixrect depths 
less than or equal to 16 are supported. 

2.1.2. Geometry Structs 

As a preliminary to the discussion of pixrects, it is convenient to define a few structs which col¬ 
lect useful geometric information. 

The struct that defines a position in coordinates {x, y) is: 

struct pr_po8 { 
int x, y; 

}; 

Leaving a pixrect undefined for the moment, this struct defines a point within a specified pix¬ 
rect: 

struct pr_prpos { 

struct pixrect *pr; 

struct pr_pos pos; 

}; 

It contains a pointer to the pixrect and a position within it. 

The following struct defines the width and height of an area: 

struct pr.size { 
int x, y; 

h 

The following struct defines a sub-area within a pixrect: 

struct pr_subregion { 
struct pixrect *pr; 

struct prjpos pos; 

struct prjsize size; 

).' 

It contains a pointer to the pixrect, an origin for the area, and its width and height. 
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2.1.3. The Pixrect Struct 

A particular pixrect is described by a pixrect struct. This combines the definition of a rectangu¬ 
lar array of pixels and the means of accessing operations for manipulating those pixels: 

struct pixrect { 

struct pixrectops *pr_ops; 

struct pr_size pr_size; 

Int prjdepth; 

caddr_t pr_data; 

}; 

The width and height of the rectangle are given in prjtize, and the number of bits in each pixel 
in pr_depth. For programmers more comfortable referring to “width” and “height,” there are 
also two convenient macros: 

^define prjwidth (pr_size.x) 

#define prjicight (pr_size.y) 

All other information about the pixrect (in particular, the location and values of pixels), is data 
private to it. Pixels are manipulated only by the set of pixrect operations described below. 
These operations will generally use information accessed through pr_data to accomplish their 
tasks. 

(This restriction is relaxed somewhat in the case of pixrects whose pixels are stored in memory; 
this provides an escape to mechanisms outside the pixrect facility for constructing and convert¬ 
ing pixrects of differing types. Memory pixrects are described in Memory Pixrects.) 


2.2. Operations on Pixrects 

Procedures are provided to perform the following operations on pixrects: 

• create and destroy them (open, region and destroy) 

• read and write the values of single pixels {get and put) 

• use RasterOp functions to affect multiple pixels in a single operation: 

write from a source to'a destination pixrect (rop) 

write from a source to a destination under control of a mask (stencil) 

replicate a constant source pattern throughout a destination (replrop) 

write a batch of sources to different locations in a single destination (batchrop) 

draw a straight line of a single source value (vector) 

• read and write a colormap (getcohrmap, putcolormap) 

• select particular bit-planes for manipulation on a color pixrect (getattributes, putattributes) 

Some of these operations are the same for all pixrecits, and are implemented by a single pro¬ 
cedure. These device-ihdependent procedures are called directly by pixrect clients. Other 
operations must be implemented differently for each device on which a pixrect may exist. Each 
pixrect includes a pointer (in its pr_ops) to a pizrectops structure, that holds the addresses of 
the particular device-dependent procedures appropriate to that pixrect. This allows clients to 
access those procedures in a device-independent fashion, by calling through the procedure 
pointer, rather than naming the procedure directly. To facilitate this indirection, the pixrect 
facility provides a set of macros which look like simple procedure calls to generic operations, and 
expand to invocations of the corresponding procedure in the pixrectops structure. 
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The description of each operation will specify whether it is a true procedure or a macro, since 
some of the arguments to macros are expanded multiple times, and could cause errors if the 
arguments contain expressions with side effects, (In fact, two sets of parallel macros arc pro¬ 
vided, which differ only in whether their arguments use the geometry structs defined above. 
Each is described with the operation.) 

2.2.1. The Pixrectops Struct 

The pixrectops struct is a collection of pointers to the device-dependent procedures for a partic¬ 
ular device: 

struct pixrectops { 


int 

(♦pro_ropX); 

int 

(*pro_8tencU)(); 

int 

(*pro_batchropX); 

int 

(♦projopX); 

int 

( * pro_destroy)(); 

int 

(♦pro_getX); 

int 

(*pro_putX); 

int 

( *pro^vcctorX); 

struct 

pixrect *(*pro_vegionX); 

Int 

(*pro_putcolormapX); 

Int 

(♦ pro_getcolormapX); 

int 

(•pro_putattributesX); 

int 

(♦pro_getattribute5)(); 


}; 

All other operations are implemented by device-independent procedures. 

2.2.2. Conventions for Naming Arguments to Pixrect Operations 

In general, the following conventions are used in naming the arguments to pixrect operations: 

Table 2-1: Argument Name Conventions 


Argument 

Meaning 

d 

destination 

» 

source 

z and y 

left and top origins 

w and h 

width and height 


2.2.3. Creation and Destruction of Pixrects 

Pixrects are created by the procedures pr_open and mem_cTeat€, by the procedures accessed by 
the macro pr_region, and at compile-time by the macro mprjttatte. Pixrects are destroyed by 
the procedures accessed by the macro pf_dettroy. Mem_create and mpr_8tatte are discussed 
under Memory Pizreett below; the rest of these are described here. 
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.2.3*1. Openi Create a Primary Display Pixrect 

The properties of a non-memory pixrect are described by a UNIX device. Thus, when creating 
the first pixrect for a device you need to open it by a call to: 

struct pixrect *pr_open(devicename) 
char «devicename; 

The default device name for your display is / devjfb {fb stands for framebuffer). Any other dev¬ 
ice name may be used provided that it is a display device, the kernel is configured for it, and it 
has pixrect support, such as, f devfbwoneO, (devfbwtwoO, fdev/cgoneO. 

Pr^open docs not work for creating a pixrect whose pixels are stored in memory; that function 
is served by the procedure mem_create, discussed under Memory Pizrects below. 

Pr^opcn returns a pointer to a pixrect struct which covers the entire surface of the named dev¬ 
ice. If it cannot, it returns NULL, and displays an error on standard error. 

2.2.3.2. Region: Create a Secondary Pixrect 

Given an existing pixrect, it is possible to create another pixrect which refers to some or all of 
the same pixels on the same device. This is called a eecondary pixrect, and is created by a call 
to the procedures invoked by the macros prjregion and prtjregiotK 

^define etruct pixrect *pr_region(pr, x, y, w, h) 
struct pixrect 'tpr; 

int X, y, w, h; 

^define atruct pixrect *prs_region(8ubrcg) 
struct prjsubregion subreg; 

The existing pixrect is addressed by pr, it may be a pixrect created by pr_open, mem_create or 
mprjitatie (a primary pixrect); or it may be another secondary pixrect created by a previous call 
to a region operation. The rectangle to be included in the new pixrect is described by x, y, w 
and h in the existing pixrect; (*, tf) in the existing pixreet will map to (0, 0) in the new one. 
Prajregion docs the same thing, but has all its argument values collected into the single struct 
avbreg. Each region procedure returns a pointer to the new pixrect. If it fails, it returns NULL, 
and displays an error on standard error. 

If an existing secondary pixrect is provided in the call to the region operation, the result is 
another secondary pixrect referring to the underlying primary pixrect; there is no further con¬ 
nection between the two secondary pixrects. Generally, the distinction between primary and 
secondary pixrects is not important; however, no secondary pixrect should ever be used after its 
primary pixrect is destroyed. 

2.2.3.3. Close / Destroy: Release a Pixrect’s Resources 

The following macros invoke device-dependent procedures to destroy a pixrect, freeing resources 
that belong to it: 
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^define pr_close(pr) 

struct pixrect *pr; 

# define pr_destroy(pr) 

struct pixrect *pr; 

# define prs_destroy(pr) 

struct pixrect ♦pr; 

The procedure returns 0 if successful, -1 if it fails. It may be applied to either primary or 
secondary pixrccts. If a primary pixrect is destroyed before secondary pixrects which refer to 
its pixels, those secondary pixrects are invalidated; attempting any operation but destroy on 
them is an error. The three macros are identical; they arc all defined for reasons of history and 
stylistic consistency. 


2.2.4. Single-Pixel Operations 

The next two operations are used to manipulate the value of a single pixel. 


2.2.4.I. Get: Retrieve the Value of a Single Pixel 

The following macros invoke device-dependent procedures to retrieve the value of a single pixel: 

#define pr_get(pr, x, y) 
atruct pixrect *pr; 

int X, y; 

^define prs_get(srcprpos) 

struct pr_prpo8 sreprpos; 

Pr indicates the pixrect in which the pixel is to be found; z and y are the coordinates of the 
pixel. For prs_get, the same arguments are provided in the single struct sreprpos. The value of 
the pixel is returned as a 32-bit unsigned integer; if the procedure fails, it returns -1. 


2.2.4.2. Put: Store a Value into a Single Pixel 

The following macros invoke device-dependent procedures to store a value in a single pixel: 

^define pr_put(pr, x, y, value) 
struct pixrect *pr; 

int X, y, value; 

# define prs_put(dstprpos, value) 
struct pr_prpos dstprpos; 

int value; 

Pr indicates the pixrect in which the pixel is to be found; z and y are the coordinates of the 
pixel. For prs_put, the same arguments are provided in the single struct dstprpos. Value is 
truncated on the left if necessary, and stored in the indicated pixel. If the procedure fails, it 
returns -1. 
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2o2*6. Constructing an Op Argument 

Tke mnlti'pixel operations described in the next section alt use a uniform mechanism for speci¬ 
fying the operation which is to produce destination pixel values. This operation is given in the 
op argument and includes several components. 

Generally, op identifies a RasterOp. This is a logical function of two or three inputs; it com¬ 
putes the value of each pixel in the destination as a function of the previous value of that desti¬ 
nation pixel, of a corresponding source pixel, and possibly a corresponding pixel in a mask. 

Two other facilities are also specified in the op argument; 

• a single, constant, source value may be specified as a color in op, and 

o the clipping which is normally performed by every pixrect operation may be turned off by set¬ 
ting the PDCPONTCLIP flag in the op. 

We describe these three components of the op argument in order. 


2.2.5.I. Specifying a RasterOp Function 

Pour bits of the ep are used to specify one of the 16 distinct logical functions which combine 
monochrome source and destination pixels to give a monochrome result. This encoding is gen¬ 
eralized to pixels of arbitrzuy depth by specifying that the function is applied to corresponding 
bits of the pixels in parallel. This emphasizes that the pixrects must be of the same depth. 
Some functions are much more common than others; the most useful are identified in the table 
Uoeful Combinationt of RaeterOpo. 

A convenient and intelligible form of encoding the function into four bits is supported by the 
following definitions: 

#define PIX_SRC 0x18 
#define PIX_DST 0x14 
#define PIX_NOT(op) (OxlE & (“op)) 

PDCSRO and PIXJ)ST are defined constants, and PKJNOT is a macro. Together, they allow a 
desired function to be specified by performing the corresponding logical operations on the 
appropriate constants. (The explicit definition of PDCNOT is required to avoid inverting non¬ 
function bits of op). 

A particular application of these logical operations allows definition of set and clear operations. 
The definition of the set operation that follows is always true, and hence sets the result: 

#define PIX_SET (PIX_SRC | PIX^NOT(PIX_SRC)) 

The definition of the clear operation is always false, and hence clears the result: 

#define PIX^CLR (PIX.SRC & PIX_NOT(PIX_SRC)) 

Other common RasterOp functions are defined in the following table: 
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Table 2-2: Useful Combinations of RjwterOps 


Op with Value 

Result 

PIX.SRC 

write (same as source argument) 

PIXJ)ST 

no-op (same as destination argument) 

PIX^SRC 1 PIX_DST 

paint (or of source and destination) 

PIX^SRC & PIX_DST 

mask (and of source and destination) 

PIX_NOT(PIX_SRC) & PDCJDST 

erase (AND destination with negation of source) 

PIX_NOT(PIX_DST) 

invert area (negate the existing values) 

PIX_SRC * PIX.DST 

inverting paint (XOR of source and destination) 


2.2.5.2. Ops with a Constant Source Value 

In certain cases, it is desirable to specify an infinite supply of pixels, all with the same value. 
This is done by using NULL for the source pixrect, and encoding a color in bits 5 - 31 of the op 
argument. The following macro supports this encoding: 

#define PIX_COLOR(color)((color)<<6) 

If no color is specified in an op, 0 appears by default; it remains necessary for the source pixrect 
specification to be NULL before this value is actually used. 

Note that the color is not part of the function component of an op argument; it should never be 
part of an argument to PIXJ^OT. 

2.2.5.3. Controlling Clipping in the Raster Op 

Pixrect operations normally clip to the bounds of the operand pixrects. Sometimes this can be 
done more efficiently by the client at a higher level. If the client can guarantee that only pixels 
which ought to be visible will be written, it may instruct the pixrect operation to bypass clip¬ 
ping checks, thus speeding their operation. This is done by setting the following flag in the op 
argument: 

#definc PIX_DONTCLIP Ox I 

The result of a pixrect operation is undefined if PDCJDONTGLIP is set and the operation goes out 
of bounds. 

Note that the PIXJ>ONTCLIP flag is not part of the function component of an op argument; it 
should never be part of an argument to PKJJOT. 
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2.2.5.4. Examples of Complete Op Argument Specification 

A very simple op argument will specify that source pixels be written to a destination, clipping as 
they go: 

op =» PDC.SRC; 

A more complicated example will be used to affect a rectangle (known to be valid) with a con¬ 
stant red color defined elsewhere. (The function is syntactically correct; it’s not clear how useful 
it is to XOR a constant source with the negation of the OR of the source and destination): 

op — (PDC.SRC ‘ PIX_NOT(PIX_SRC | PIX.DST) ) | PIX_COLOR(red) 1 PIX.DONTCLIP 

2.2.6. Multi-Pixel Operations 

The following operations all apply to multiple pixels at one time: rop, eteneil, replrop, batckrop, 
and vector. With the exception of vector, they refer to rectangular areas of pixels. They all use 
a common mechanism, the op argument described in the previous section, to specify how pixels 
are to be set in the destination. 


2.2.6.1. Rop: RasterOp Source to Destination 

Oevice-dei>endent procedures invoked by the following macros perform the indicated raster 
operation from a source to a destination pixrect: 

#define pr_rop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 
struct pixrect *dpr, *spr; 

Int dx, dy, dw, dh, op, sx, sy; 

#define pr8jrop(dstregion, op, srcprpos) 
struct prjsubregion dstregion; 

!nt op; 

struct pr_prpos srcprpos; 

Dpr addresses the destination pixrect, whose pixels will be affected; {dx, dy) is the origin (the 
upper-left pixel) of the affected rectangle; dw and dh are the width and height of that rectangle. 
Spr specifies the source pixrect, and («*, ay) an origin within it. Spr may be NULL, to indicate a 
constant source specified in the op argument, as described above; in this case ax and ay are 
ignored. Op specifies the operation which is performed; its construction is described in preced¬ 
ing sections. 

For prajrop, the rfpr, dx, dy, dw and dh arguments are all collected in a pr_aubregion struct, 
defined above under Geometry Structa. 

Raster operations are clipped to the source dimensions, if those are smaller than the destination 
site given. Rop procedures return -1 if they fail, 0 if they succeed. 

Source and destination pixrects generally mus be the same depth. The only exception allows 
depth-l pixrects to be sources to a destination of any depth. In this case, source pixels = 0 are 
interpreted as 0 and source pixels = 1 are written as the maximum value which can be stored 
in a destination pixel. 
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2.2.6.2. Stencil: RasterOps through a Mask 

Device-dependent procedures invoked by the following macros perform the indicated raster 
operation from a source to a destination pixrect only in areas specified by a third (stencil) pix- 
rect: 

^define prjjtencil(dpr,dx,dy,dw,dh,op,stpr,8tx,sty,spr,sx,sy) 
struct pixrect *dpr, ♦stpr, *spr; 

int dx,dy,dw,dh,op,stx,8ty,sx,sy; 

#define prs_stencil(dstregion, op, stenprpos, srcprpos) 
struct pr.subregion dstregion; 

Int op; 

struct pr_prpos stenprpos, srcprpos; 

Stencil is identical to top except that the source pixrect is written through a stencil pixrect 
which functions as a spatial write-enable mask. The stencil pixrect must have depth equal to 1. 
The indicated raster operation is applied only to destination pixels where the stencil pixrect is 
non-Eero. Other destination pixels remain unchanged. The rectangle from {tx,ey) in the source 
pixrect $pr is aligned with the rectangle from {atz,ety) in the stencil pixrect stpr, and written to 
the rectangle at (dz,dy) with width dw and height dh in the destination pixrect dpr. The source 
pixrect apr may be NULL, in which case the color specified in op is painted through the stencil. 
Clipping restricts painting to the intersection of the destination, stencil and source rectangles. 

2.2.6.3. Replrop: Replicating the Source Pixrect 

Often the source for a raster operation consists of a pattern that is used repeatedly, or repli¬ 
cated to cover an area. If a single value is to be written to all pixels in the destination, the l^st 
way is to specify that value in the color component of a rop operation. But when the pattern is 
larger than a single pixel, a mechanism is needed for specifying the basic pattern, and how it is 
to be laid down repeatedly on the destination. The pr_replrop procedure replicates a source 
pattern repeatedly to cover a destination area: 

prj‘eplrop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

■truct pixrect *dpr, ♦spr; 

!nt dx, dy, dw, dh, op, sx, sy; 

^define prsjeplrop(dsubrcg, dp, sprpos) 
struct pr_subregion dsubreg; 

struct pr_prpos sprpos; 

Dpr indicates the destination pixrect. The area affected is described by the rectangle defined by 
dx, dy, dw, dh . Spr indicates the source pixrect, and the origin within it is given by ay. The 
corresponding prajreplrop macro generates a call to prjreplrop, expanding its daubreg into the 
five destination arguments, and sprpos into the three source arguments. Op specifies the opera- 
tion to be performed, as described above under Constructing Op Arguments. 

The effect of replrop is the same as though an infinite pixrect were constructed using copies of 
the source pixrect laid immediately adjacent to each other in both dimensions, and then a rop 
was performed from that source to the destination. For instance, a standard gray pattern may 
be painted across a portion of the screen by constructing a pixrect that contains exactly one tile 
of the pattern, and by using it as the source pixrect. 
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The alignment of the pattern on the destination is controlled by the source origin given by sx, 
sy. If these values are 0, then the pattern will have its origin aligned with x.ae position in the 
destination given by dz, dy. The most common other alignment is used to preserve a global 
alignment with the destination, for instance, to repair a portion of a gray. In this case, the 
source pixel which should be aligned with the destination position is the one which has the same 
coordinates as that destination pixel, modulo the size of the source pixrect. Replrop will per¬ 
form this modulus operation for its clients, so it suffices in this case to simply copy the destinar 
tion position {dx, dy) into the source position {tx, $y). 

2.2.0.4* Batch RasterOp: Multiple Source to the Same Destination 

Applications such as displaying text perform the same operation from a number of source pix- 
rects to a single destination pixrect in a fashion that is amenable to global optimization. 
Device-dependent procedures invoked by the following macros perform raster operations on a 
sequence of sources to successive locations in a common destination pixrect: 

struct batchitem { 

struct pixrect *bi_pr; 

struct pr_pos bi_pos; 

}; 

#define pr_batchrop(dpr, dx, dy, op, items, n) 
struct pixrect *dpr; 

Int dx, dy, op, n; 

struct batchitem itemsf ]; 

# define pr8_batchrop(datpos, op, items, n) 
struct prj)rpos dstpos; 

Int op, n; 

struct batchitem items [ ]; 

The sequence of sources used by a batehrop procedure is an array of batchitem structures. Each 
item specifies a source pixrect and an advance in * and y. The whole of each source pixrect is 
used, unless it needs to be clipped to fit the destination pixrect: the elements of bt_poa are used 
to update the destination position, not as an origin in the source pixrect. 

Batehrop procedures take a destination, specified by dpr, dz and dy, or by dstpos in the case of 
prsjbatekropi an operation specified in op, as described in Constructing Op Arguments above, 
and an array of batehitems addressed by the argument items, and whose length is given in the 
argument n> 

The destination position is initialized to the position given by dx and dy. Then, for each batchu 
tern, the offsets given in bijpos are added to the previous destination position, and the operation 
specified by op is performed on the source pixrect and the corresponding rectangle whose origin 
is at the current destination position. Note that the destination position is updated for each 
item in the batch, and these adjustments are cumulative. 

The most common application of batehrop procedures is in painting text; additional facilities to 
support this application are described below under Text Facilities for Pixrects. Note that the 
definition of batehrop procedures supports variable-pitch and rotated fonts, and non-roman writ¬ 
ing systems, as well as simpler text. 
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2.2.6.5. Vector: Draw a Straight Line 

Device-dependent procedures invoked by the following macros draw a vector of unit width 
between two points in the indicated pixrect: 

#define pr_vector(pr, xO, yO, xl, yl, op, value) 

■truct pixrect ♦pr; 

int xO, yO, xl, yl, op, value; 

#define prs_vector(pr, posO, posl, op, value) 
struct pixrect ‘pr; 

struct pr_pos posO, posl; 

int op, value; 

Vector procedxures draw a vector in the pixrect indicated by pr, with endpoints at (zO, yO) and 
(zJ, yJ), or at posO and posl in the case of prs^vector. Portions of the vector lying outside the 
pixrect are clipped as long as PIXJ)ONTCLIP is 0 in the op argument. The op argument is con¬ 
structed as described above under Construetiny Op Arguments; and veJue specifies the resulting 
value of pixels in the vector. If the color in op is non-zero, it takes precedence over the value 
argument. 


2.2.7. Colormap Access 

A colormap is a table which translates a pixel value into 8-bit intensities in red, green, and blue. 
For a pixrect of depth n, the corresponding colormap will have 2“ entries. The two most com¬ 
mon cases are depth-1 (monochrome with two entries) and depth-8 (with 250 entries). Memory 
pixrects do not have colormaps. 


2.2.7.1. Get Colormap 

The following macros invoke device-dependent procedures to read all or part of a colormap into 
arrays in memory: 

^define pr^etcoIormsp(pr, index, count, red, green, blue) 
struct pixrect *pr; 

lot index, count; 

unsigned char red [ ], green[ ], blue[ ]; 

^define prs_getcoIormap(pr, index, count, red, green, blue) 
struct pixrect *pr; 

int index, count; 

unsigned char red [ ], green[ ], blue[ ]; 

These two macros have identical definitions; both are defined to allow consistent use of one set 
of names for all operations. 

Pr identifies a pixrect whose colormap is to be read; the count entries starting at index are read 
into the three arrays. 

For monochrome pixrects the same value is written to corresponding elements of the red, green 
and blue arrays. These array elements will have their bits either all cleared, indicating black, or 
all set, indicating white. By default, the 0th (background) element is white, and the 1st ((fore¬ 
ground) eli^pient is black. 
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2.2.7.2. Put Colormap 

The following macros invoke device-dependent procedures to store from memory into all or part 
of a colormap: 

5 ^define pr_putcolormap(pr, index, count, red, green, blue) 
struct pixrect *pr; 

int index, count; 

unsigned char red {], green[ ], blue[ ]; 

#4efine prs_putcolormap(pr, index, count, red, green, blue) 
jitruct pixrect *pr; 

int index, count; 

unsigned char red [ ], green[), blue{ J; 

These two macros have identical definitions; both are defined to allow consistent use of one set 
of names for ail operations. 

The count elements starting at index (zero origin) in the colormap for the pixrect identified by 
pr are loaded from corresponding elements of the three arrays. 

For monochrome pixrects, the only value considered is red[0]. If this value is 0, then the pix¬ 
rect will be set to a dark background and light foreground. If the value is non-zero, the fore¬ 
ground will be dark, e.g. black-on-white. Monochrome pixrects are dark-on-light by default. 

Note: Fu)| functionality of the colormap is not supported for depth-1 pixrects. Colormap 
changes t© depth-1 pixrects apply only to subsequent operations whereas a colormap change to 
a color deyice instantly changes all affected pixels on the display pixrect. 

2.2.7.3. Provision for Inverted Video Pixrects 

Video inversion is accomplished by manipulation of the colormap of a pixrect. The colormap of 
a depth-1 pixrect has two elements. The following procedures provide video inversion control: 

pr_blackonwhitc{pr, min, max) 
struct pixrect *pr; 

int min, max; 

pr>whiteonblack(pr, min, max) 
struct pixrect '•'pr; 

|nt min, max; 

prjreverBevidco(pr, min, mzoc) 
struct pixrect *pr; 

int min, max; 

In each procedure, pr identifies the pixrect to be affected; min is the lowest index in the color- 
map, specifying the background color, and max is the highest index, specifying the foreground 
color. These will most often be 0 and 1 for monochrome pixrects; the more general definitions 
allow coIormai>'sharing schemes, such as the one described below in Colormap Sharing, in the 
chapter Overlapped Windotps: Imaging Facilitieo. 

“Black-onrFhite" means that zero (background) pixels will be painted at full intensity, which is 
usually white. Prjblackonwhite sets all bits in the entry for colormap location min and clears all 
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bits in cotormap location max. 

“Wbite-offi-black" means that zero (background) pixels will be painted at minimum intensity, 
which is usually black. Pr_whiteonblack clears all bits in colormap location min and sets all bits 
in the entry for colormap location max. 

Reversevideo exchanges the min and max color intensities. 

These procedures are ignored for memory pixrects. 


2.2*8. Attributes for Bitplane Control 

In a color pixrect, it is often useful to define bitplanes which may be manipulated indepen* 
dently; operations on one plane leave the other planes of an image unaffected. This is normally 
done by assigning a plane to a constant bit position in each pixel. Thus, the value of the Ah bit 
in all the pixels defines the Ah bitplane in the image. It is sometimes beneficial to restrict pix* 
rect operations to affect a subset of a pixrect*s bitplanes. This is done with a bitplane mask. A 
bitplane mask value is stored in the pixrect’s private data and may be accessed by the attribute 
operations. 


2.2.8.1. Get Attributes 

Device-dependent procedures invoked by the following macros retrieve the mask which controls 
which planes in a pixrect are affected by other pixrect operations: 

#define pr_getattributes(pr, planes) 
struct pixrect *pr; 

int iplanes; 

^define pr8_getattributes(pr, planes) 
struct pixrect *pr; 

int ^planes; 

Pr identifies the pixrect; its current bitplanes mask is stored into the word addressed by planes. 
If planes is NULL, no operation is performed. 

The two macros are identically defined; both are provided to allow consistent use of the same 
style of names. 

2.2.8.2. Put Attributes 

Device-dependent procedures invoked by the following macro manipulate a mask which controls 
which planes in a pixrect are affected by otker pixrect operations: 

^define pr^utattributes(pr, planes) 
struct pixrect *pr; 

int *planes; 

^define prs_putattributes(pr, planes) 
struct pixrect *pr; 

int *planes; 
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Pr identifies the pixrect to be affected; its mask is set so that only the planes identified by 1-bits 
in the value of planet will be read or written by subsequent pixrect operations. If planet is 
NULL, no operation is performed. 

The two macros are identically defined; both are provided to allow consistent use of the same 
style of names. 

Planet may be used to enforce that no pixel values outside of a pixrects colormap section are 
written. In other words, the planet argument is a bitplane write-enable mask. Only those bits 
of the pixel corresponding to a 1 in the same bit position of *planee will be affected by pixrect 
operations. For example, if *planet » 1 in a destination pixrect, subsequent operations will 
only modify bit 0 of the destination pixels. 

Note: If apy planet are masked off by a call to prjputattn'butet, no further read or write access 
to those planes is possible until a subsequent call to pr_j)utattributet unmasks them. 


2.3. Text Facilities for Pixrects 

Displaying text is an important task in many applications, so pixrect-level facilities are provided 
to address it directly. These facilities fall into two main categories: a standard format for 
describing fonts and character images, with routines for processing them; and a set of routines 
which take a string of text and a font, and handle various parts of painting that string in a pix¬ 
rect. 

% 

2.3.1. Pixfonts and Pixchars 

The following two structs are used to describe fonts and character images for pixrect-level text 
facilities: 

■truet pixchar { 

■truet pixrect *pcjpr; 

atruct pr_po8 pcjiome; 

struct prjpos pc^adv; 

}; 

struct pixfont { 

struct pr_8ii!e pfjdefaultsize; 

struct pixchar pf_char[256]; 

}; 

A pixfont contains an array of pixekart, indexed by the character code; it also contains the size 
(in pixels) of its characters when they are all the same. (If the size of a font’s characters varies 
in one dimension, that value in pf_defaulttize will not have anything useful in it; however, the 
other may still be useful. Thiis, for non-rotated variable-pitch fonts, pf^defaulttize.y will still 
indicate the unleaded interline spacing for that font.) 

Note: The definition of a pixfont is expected to change. 

The pixchar defines the format of a single character in a font. The 2 u;tual image of the charac¬ 
ter is stored in a pixrect (a separate pixrect for each character) addressed by pc_pr. Characters 
that do not have a displayable image will have NULL in their entry in pe_pr. Pe^home is the 
origin of that image (its upper left corner) relative to the character origin. Characters are noi^ 
mally placed relative to a 6ase/tne, which is the lowest point on characters without descenders. 
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The leftmost point on a character is normally its origin, but kerning or mandatory letter spac¬ 
ing may move the origin right or left of that point. Pc_adv is the amount the destination posi¬ 
tion is changed by this character; that is, the amounts in pe_adv added to the current origin will 
give the origin for the next character. While normal text only advances horisontally, rotated 
fonts may have a vertical advance. Both are provided for in the font. 


2.3.2. Operations on Pixfonts 

Before a process may tise a font, it must ensure that font has been loaded into virtual memory; 
this is done with pf_opcn: 

struct pixfont *pf_open(name) 
char <*name; 

This procedure opens the file with the given name. The file should be a font file as described in 
ti/on((5): The file is converted to pixfont format, allocating memory for its associated structs and 
reading in the data for it from disk. A NULL is returned if the font cannot be opened. 

The procedure: 

struct pixfont *pf_default() 

performs the same function for the system default font, normally a fixed-pitch, 16-point sans 
serif font with upper-case letters 12 pixels high. If the environment parameter DE^AULT_FONT 
is set, its value will be taken as the name of the font file to be opened by pf_default. 

Note. pf_open and pf_default load a new copy of the font every time they are called, even if the 
font has already been loaded. To conserve memory, clients may use pxajpjtytopen, described in 
Overlapped Windows: Imaging Facilities, or take care only to open a font once in a process. 

When a process is finished with a font, it should call pf_chse to free the memory associated with 
it: 

pfjclose(pf) 

•truct pixfont *pf; 

P/should be the font handle returned by a previous call to pf_open or pf^default. 


2.3.3. Pixrect Text Display 

Characters are written into a pixrect with the pfjtext procedure: 

pf_text(where, op, font, text) 

■truct pr_prpos where; 

Int op; 

struct pixfont *font; 

char *text; 

Where is the destination for the start of the text (nominal left edge, baseline; see Pixfonts); op is 
the raster operation to be used in writing the text, as d^ribed in Constructing Op Arguments; 
font is a pointer to the font in which the text is to be displayed; and text is the actual null- 
terminated string to be displayed. 

The following procedure paints “transparent” text: it doesn’t disturbing destination pixels in 
blank areas of the character’s image: 
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pf_fctext(where, op, font, text) 
etruct prjrpos where; 
int op; 

struct pixfont *font; 

char *text; 

The arjraments to this procedure are the same as for pfjtezt The characters’ bitmaps are used 
£3 a stencil, and the color specified in op is squirted through the stencil. 

(For moncchrome pixrects, the same effect can be achieved by using PDCSRO | PDLPST as the 
function in the op; this procedure is required for color pixrects.) 

Auxiliary procedures used with pfjtext include: 

struct pr_8iie pfjbextbatch(wherc,lengthp, font, text) 
etruet batchitem whereQ; 

int «iengthp; 

struct pixfont *font; 

char *text; 

struct prjsiie pf_textwidth(Ien, font, text) 
lot ten; 

struct pixfont *font; 

char *text; 

Pf_tcxtbatch is used internally by pfjtezt", it constructs an array of batchitems and records its 
length, as required by batchrop (see Batch Ratter Op), Where should be the address of an array 
to be filled in, and lengthp should point to a maximum length for that array. Text addresses the 
null •tc: 2 ninatcd string to be put in the batch, and font the pixfont to be used to display it. On 
its return, *lengthp will have been modified to be the number of batchitems actually used for 
text, 

Pfjextwtdth returns a pr^siee which contains the total dimension of the string of the first ten 
characters in text, when formatted in the indicated font. 


2.4. Memory Pixrects 

Pixrects which store their pixels in memory, rather than displaying them on some display, have 
several special properties. Like all other pixrects, their dimensions are visible in the pr_tize and 
pr^depth elements of their pixrect struct, and the device^dependent operations appropriate to 
manipulating them are available through their pr^opt. Beyond this, however, the format of the 
data which describes the particular pixrect is also public: pr_data will hold the address of a 
mpr_data struct, described below. There is also a public procedure, mem_create, which dynami¬ 
cally allocates a new memory pixrect, and a macro, mpr_ttatie, which can be used to generate 
an initialized memory pixrect in the code of a client program. Thus, a client may construct and 
manipulate memory pixrects using non-pixrect operations. 


2.4.1. The Mpr_data Struct 

The pr_data element of a memory pixrect points to an tnpr_data struct, which contains the 
information needed to deal with a memory pixrect: 
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struct mpr_data { 

int mdjinebytes; 

short *md_iniage; 

struct pr_po3 md_off8et; 

short md_primar 7 ; 

short md_^ags; 

); 

#define MP_DISPLAY 
#defihe MPJREVERSEVIDEO 

LinebyteM is the number of bytes stored in a row of the primary pixrect. This is the difference 
in the addresses between two pixels at the same s-coordinate, one row apart. Because a secon¬ 
dary pixrect may not include the full width of its primary pixrect, this quantity cannot be com¬ 
puted from the width of the pixrect — see Region. The actual pixels of a memory pixrect are 
stored someplace else in memory, usually an array, which md_image points to; the format of 
that area is described in the next section. The creator of the memory pixrect must ensure that 
tnd_image contains an even address. Md_offtet is the x-g position of the first pixel of this pix¬ 
rect in the array of pixels addressed by mdjimage. Md_primory is 1 if the pixrect is primary 
and had its image allocated dynamically (e.g. by mem_ereate). In this case, mdjimage will point 
to an area not referenced by any other primary pixrect. This flag is interrogated by the deatroy 
routine: if it is 1 when that routine is called, the pixrect’s image memory will be freed. 

{Md_flaga & MPJDISPLAY) is non-zero if this memory pixrect is in fact a display device. Other¬ 
wise, it is 0. {MdJlaga & MPJtEVERSEVIDEO) is 1 if reveraevideo is enabled for the display dev¬ 
ice. Md_flaga is present to support memory-mapped display devices like the Suu-2 black-and- 
white video device. 

2.4.2. Pixel Layout in Memory Pixrects 

In memory, the upper-left corner pixel is stored at the lowest address. This address should be 
even. That first pixel is followed by the remaining pixels in the top row, left-to-right. Pixels 
are stored in successive bits without padding or alignment. For pixels more than 1 bit deep, it is 
possible for a pixel to cross a byte boundary. However, rows are rounded up to 10-bit boun¬ 
daries. After any padding for the top row, pixels for the row below are stored, and so on 
through the whole rectangle. 

2.4^3. Creating Memory Pixrects 


2.4.3.1. Mem_create 

A new primary pixrect is created by a call on the procedure memjereate. 

struct pixrect *mem_create(w, h, depth) 

int w, h, depth; 

VV, h, and depth specify the width and height in pixels, and depth in bits, of the new pixrect. 
Sufficient memory to hold those pixels is allocated and cleared to 0, new mpr_data and pixrect 
structs are allocated and initialized, and a pointer to the pixrect is returned. If this can not be 
done, the return value is NULL. 
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2.4.3.2. Static Memory Pixrects 

A memory pixrect may be created at compile time by using the mpr_»tatie macro: 

H-de&ne mpr_static(name, w, h, d, image) 
char *name; 

Int V, b, d; 

■hort * image; 

where name is a token to identify the generated data objects; w, A, and d are the width and 
height in pixels, and depth in bits of the pixrect; and image is the address of an even-byte 
aligned data object that contains the pixel values in the format described above. 

The macro generates two structs: 

struct mprjdata name_data ; 

struct pixrect name ; 

The mpr_data is initialised to point to all of the image data passed in; the pixrect then refers to 
mem_op» and to name_data. 

Note: Contrary to its name, this macro generates structs whose storage class is extern. 
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Chapter 3 

Overlapped Windows: Imaging Facilities 


This chapter and the following two deal with the tunwindow layer of the window system, which 
provides facilities for managing windows with overlap and concurrency. This chapter is 
specifically concerned with generating images in such an environment. Chapter 4 deals with 
control of the windows, manipulating their size, location, and other structural characteristics. 
Chapter 5 describes the facilities for serializing multiple input streams and distributing them 
appropriately to multiple windows. The term “sunwindow layer” comes from the name of the 
library that contains its implementation. 

At this level of the system, a window is treated as a device: it is named by an entry in the /dev 
directory; it is accessed by the open(2) system call; and the usual handle on the window is the 
file deacriptor (or /rf) returned from that call. 

For this chapter, however, a window may be considered as simply a rectangular area with con¬ 
tents maintained by some process. Multiple windows, maintained by independent processes, 
may coexist on the same screen; SunWindows allows them to overlap, sharing the same (x, y) 
coordinates, and proceeding'concurrently, while maintaining their separate identities. 

Window system facilities may also be used to construct a non-overlapped environment; the win¬ 
dow system facilities required are much the same as for constructing on overlapping environ¬ 
ment. 


3.1. Window Issues: Controlled Display Generation 

Multiple windows on a display introduce two new issues, which may be broadly characterized 
as; 1) preventing the window from painting where or when it shouldn’t, and 2) ensuring that it 
does paint whenever and wherever it should. The first includes clipping and locking; the latter 
covers damage repair and fixups. 


3.1.1. Clipping and Locking 

Clipping constraitts a window to draw only within the boundaries of its portion of the screen. 
This area is subject to changes beyond the control of a window’s process — another window 
may be opened on top of the first, covering part of its contents, or a window may be shrunk to 
make room for another alongside it. Thus, it is convenient for the window system to maintain 
up-to-date information on which portions of the screen belong to which windows, and for the 
windows to consult that information whenever they are about to draw on the screen. 

Locking prevents window processes from interfering with each other in several ways: 
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• Raster hardware may require several operations to complete a change to the display; one 
process’ use of the hardware should be protected from interference by others during this 
critical interval. 

• Changes to the arrangement of windows must be prevented while a process is painting, lest 
an area be removed from a window as it is being painted. 

• A software cursor that the window process does not control (the kernel is usually responsi¬ 
ble for the cursor) may have to be removed so that it does not interfere with the window’s 
image. 

Clipping and locking are described in more detail in Locking and Clipping. 

3.1.2. Damage Repair and Fixups 

A window whose image does not appear entirety as it should on the screen is said to be dam- 
aged. A common cause of damage is being first overlaid, and then uncovered, by another win¬ 
dow. When a window is damaged, a portion of the window’s image must be repaired. Note 
that the requirement for repairing damage may arise at any time; it is completely outside the 
window’s control. 

When a process performs some operation which includes reading a portion of its window, for 
instance copying a part of the image from one region to another to implement scrolling, it may 
find the source pixels obscured. This necessitates a fixup, in which that portion of the image is 
regenerated, similar to repairing damage. Unlike damage generation, the need to do some fixup 
is provoked only in response to an action of the window's process, e.g., scrolling. 

3.1.3. Retained Windows 

Either form of regeneration may be done by recomputing the image; this approach is reasonable 
for applications like text where there is some underlying representation from which the display 
can be recomputed easily. For images which require considerable computation, SunWindows 
provides a retained window, whose image is maintained in memory as well as on the display. 
Such a window may have its image recopied to the display as needed to repair damage. The 
mechanism for making a window retained is described in Pixwins. 

3.1.4* Colormap Sharing 

On color displays, colormap entries are a constrained resource. When shared among multiple 
applications, colormap usage requires arbitration. For example, consider the following applicar 
tions running on the same display at the same time in different windows: 

• Application program X needs 64 colors for rendering VLSI images. 

• Application program Y needs 32 shades of gray for rendering black and white photographs. 

• Application program Z needs 256 colors (assume this is the entire colormap) for rendering full 
color photographs. 

Colormap usage control is handled as follows: 

• To determine how X and Y figure out what portion of the colormap they should use so they 
don’t access each others’ entries, SunWindows provides a resource manager that allocates a 
colormap segment to each window from the shared colormap. To reduce duplicate colormap 
segments, they sire named and can be shared among cooperating processes. 
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• To hide concerns about knowing the correct offset to the start of a colormap segment from 
routines that access the image, SunWindow initializes the image of a window with the color- 
map segment offset. This effectively hides the offset from the application. 

• To accommodate Z if its large colormap segment request cannot be granted, Z’s colormap is 
loaded into the hardware, replacing the shared colormap, whenever input is directed towards 
Z’s window. Z’s request is not denied even though it is not allocated its own segment in the 
shared colormap. 

• To control the blanking that occurs when colormap swapping causes all but Z’s image to 
disappear. Given an unfortunate choice of colors, SunWindow ensures that the background 
(colormap segment entry 0) and foreground (colormap segment entry size-1) for all segments 
in shared colormap are the same. This colormap content restriction has the affect of eliminat¬ 
ing blanking. 

3.1.5. Process Structure 

In SunWindows, access to the screen is performed in each user process, instead of in a single, 
central, fully debugged screen management process. This increases the possibility of an 
incorrect user process damaging the display area of other application processes. Several com¬ 
pensating factors justify this approach: 

• Clients may access this open system at whichever level is most convenient. Clients who 
require the ultimate efficiency of direct screen access need not sacrifice the window manage¬ 
ment functions of the window system. 

• Leaving processing in user processes promotes efficiency in both implementation and execu¬ 
tion: making and testing extensions and modifications is much easier in user code than in the 
kernel. 


3.1.0. Imaging with Windows 

A detailed discussion of ima^ng with windows follows. We begin with a description of the basic 
data structures that are used in this level of Sunwindows. These are a primitive geometric facil¬ 
ity, the reet, for describing rectangles, and the basic structure, the ptxwin, that describes a win¬ 
dow on the screen with its associated state and operation vectors. 

Following is a brief discussion of the simple process of creating and destroying pixunns. This is 
followed by a detailed description of the approach to locking and clipping, which leads naturally 
into a discussion of library routines that access a ptxwin*» pixels. Detecting and repairing dam¬ 
age is treated next. 

3.1.7. Libraries and Header Files 

The procedures described in this chapter are provided in the aunwtndow library 
{f utrf libHibiunwindow.a). The header file fuar!includejaunwindowf windowjia.h contains all the 
indudea that are required by a program using the facilities described in this chapter. 
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3.2. Data Structures 

Here are some data structures used in the implementation of pixwins. Be sure you understand 
recti before preceding. Descriptions of the data structure internals are also provided for addi¬ 
tional information. 


3.2.1. Rects 

Throughout Sunwindows, images are dealt with in rectangular chunks; where complex shapes 
are required, they are built up out of groups of rectangles. The basic description of a rectangle 
is the rect struct, defined in the header file Juirf includef tvnwindowf rect.h. The same file con¬ 
tains definitions of several useful macros and procedures for dealing with recti. 

Where a window is partially obscured, its visible portion generally cannot be described by a sim¬ 
ple rectangle; instead a list of non-overlapping rectangulzu* fragments which together cover the 
visible area is used. This rectUit is declared, along with its associated macros and procedures in 
the file Juirf include!iunwindowjrectUit.h, 

At this point we only discuss the rect struct and its most useful macros; a full description of 
both recti and rectliiti is in Appendix A. 

^define coord short 

struct rect { 

coord r_left; 

coord r_top; 

short r_width, 

short r_height; 

}; 

In the context of a window, the rectangle lies in a coordinate system whose origin is in the 
upper left-hand comer, and whose dimensions are given in pixels. Two macros determine an 
edge not given explicitly in the rect. These macros are: 

#define rect_right(rp) 

^define rect3ottom(rp) 

struct rect *rp; 

These macros return the coordinate of the last pixel within the rectangle on the right or bot¬ 
tom, respectively. 


3.2.2. Pixwins 

Pizwim are the basic imaging elements of the overlapped window system. The window layer of 
the system uses pixwins to represent pixrects on a window surface. The pixwin thus describes 
the window image and a set of routines to operate on the window. 

A client of the window system has a rectangular window in which it displays information for the 
user. Because of overlapping, however, it is not always possible to display information in all 
parts of a client's window. Parts of an image may have to be displayed at some point long after 
they were generated, as a portion of the window is uncovered. The clipping and repainting 
necessary to preserve the identity of the rectangular image across interference with other objects 
on the screen is handled by manipulations on pixwins. 
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Tke pixwin struct ts defined in f uarf includef sunwindowf ptxwin.h: 


struct pixwin 
struct 
caddr_t 
int 
int 

struct 
struct 
struct 
struct 
struct 
ch&r 

}; 

The pixwin refers 
pw^>ixrect. 

If the image displayed in the pixwin required a large effort to compute, it will be worth saving a 
backup copy of the whole image, making the window a retained window. This is done by creat¬ 
ing an appropriate memory pixrect as described in Memory Pixrecta, and storing a pointer to it 
in pw_prretained. 

Portions of the image which could not be accessed by an operation which attempted to read 
pixels from the pixwin are indicated by pw_fizvtp. 

Pw_opa is a pointer to a vector of operations in screen access macros to call either the pixwin 
software level or as an optimization, the pixrect software directly. The structure pixrectops was 
discussed in Pixrectopt. The pwjopahandle is the data handle passed to the operations of 
pw_opa. Pw_optx and pw_opty are additional offset information that screen access macros use. 
These three fields are dynamically altered based on locking and clipping status. 

Pw_clipdata is a collection of information of special interest to locking and clipping. Pw_clipop» 
points to a vector of operations which are used in locking and clipping. The declarations of 
these last two structs are discussed more fully in Pixwin_elipdata Struct, Pixwin_clipopa Struct, 
and subsequent sections. 

Pw__cmaname the identifier of the colormap segment that this pixwin is currently using. This 
value should only be accessed via pw_aetcmaname and pw_getcmaname procedures described 
below. 


pixrectops *pw_op3; 

pw_opshandle; 

pw_opsx; 

pwjopsy; 

rectlist pw_fixup; 

pixrect *pw_pixrect; 

pixrect *pw_prretained; 

pixwin_clipops *pw_clipop8; 

pixwin_clipdata *pw_clipdata; 

pw_cmsname[20]; 

to a portion of some device, typically a display; the device is identified by 
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3.2.3. Pixwin_clipdata Struct 

struct pixwin_c!ipdata { 


int 

pwcd_windowfd; 

short 

pwcd_3tate; 

struct 

rectlist pwcd_clipping; 

int 

pwcd_clipid; 

int 

pwcd_damagedid; 

int 

pwcdjockcount; 

struct 

pixrect *pwcd_prmulti; 

struct 

pixrect *pwcd_prsingle; 

struct 

pixwin_priist *pwcd_prl; 

struct 

rectlist pwcd_clippingsorted[RECTS_SORTS]; 

struct 

rect ♦pwcd_regionrect; 


}l 

#define PWCD_NULL 0 

#define PWCD_MULTIRECTS 1 

#define PWCD.SINGLERECT 2 

#define PWCD_USERDEFINE 3 

struct pixwin_prlist { 

struct pixwinjrlist *prl_next; 

struct pixrcct '»prl_pixrect; 

_ int prl_x, prljr; 

}; 

Pwcd_windowfd is a file descriptor for the window being accessed. \\^thin the owning process, it 
is the standard handle on a window. A description of the interplay between windows and 
pixwina continues in Pixwin Creation and Deatruetion. The portions of the window's area acces* 
jible through the pixwin are described by the pwcd_cKpping rectliat. Pwedjregionrect, if not 
NULL, points to a reet that is intersected with pwed_elipping to further restrict the portions of 
the window’s area accessible through the pixwin. Pwcd_j:lipid and pwed__damagedid identify the 
most recent reetliata retrieved for a window. Pwcdjiockcount is a reference count used for 
nested locking, as described in Locking below. Copies of this pwcdjclipping, sorted in directions 
convenient for copy operations, are stored in pwcd_clippingaorted. 
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Pwcd,jtate can be one of the following: 

Table 3-1: Clipping State 


State 

Meaning 

PWCD_NULL 

no part of window visible 

PWCD.MULTIRECTS 

must clip to multiple rectangles 

PWCD_SINGLERECT 

need clip to only one rectangle 

PWCD_ySERDEFINE 

the client program will be 
responsible for setting up the 
clipping 


Pwcd_prmultt is the pixrect for drawing when there are multiple rectangles involved in the clip¬ 
ping. Pwcd_prting{e is the pixrect for clipping when there is only one rectangle visible. 

Pwedjpri is a list of pixrecU that may be used for clipping when there are multiple rectangles 
involved. For vector drawing, these clippers mast be used maintain stepping integrity across 
abutting rectangle boundaries. The prl_x and pr/_y fields in the ptxwin_prli»t structure are 
offsets from the window origin for the associated prl_pixrect 

3.2.4* Pixwin_clipop8 Struc^j 

struct pixwin_clipops { 

Int (*pwcoJockX), 

Int (*pwco_unIockX), 

Int (♦pwcoj’esetX), 

Int (*pwco_getclippingX); 

}; 

The pw_cltpopt struct is a vector of pointers to system-provided procedures that implement 
correct screen access. These are siccessed through macros described in Locking and Clipping. 

3.3. Fix win Creation and Destruction 

To create a pixwin, the window to which it will refer must already exist. This task is accom¬ 
plished with procedures like win^getnewwindow and win_$etrect, described in Window Manipula¬ 
tion, or, at a higher level, tool_cfeate and tool_create9ubwindow, described in Suntool: Tools and 
Subwindows. The pixwin is then created for that window by a call to pw_open: 

struct pbcwin *pw_open(fd) 
int fd; 

Pw_open takes a file descriptor for the window on which the pixwin is to write. A pointer to a 
pixwin struct is returned. At this point the pixwin describes the exposed area of the window. If 
the client wants a retained pixwin, pw_prretained should be set to point to an appropriately- 
sized memory pixrect after pw_open returns. 
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When a client is finished with a window, it should be released by a call to: 

pw_close(pw) 

struct pixwin *pw; 

Pw_close frees any dynamic storage associated with the pixwin, including its pw_prretained pix- 
rect if any. If the pixwin has a lock on the screen, it is released. 


3.3.1. Region Creation 

One can use pixwins to clip rectangular regions within a window’s own rectangular area. The 
region operation creates a new pixwin that refers to an area within an existing one: 

struct pixwin *pw_jegion(pw, x, y, w, h) 
struct pixwin •tpw; 

int X, y, w, h; 

The pixwin which is to serve as the source is addressed by pw, x, y, w and h describe the rectan¬ 
gle to be included in the new pixwin. The upper left pixel in the returned pixwin is at coordi¬ 
nates (0,0); this pixel has coordinates {x, y) in the source pixwin. 


3.4. Locking and Clipping 

Before a window process reads from or writes to the screen, it must satisfy several conditions: 

• It should obtain exclusive use of the display hardware, 

• The position of windows on the screen should be frozen, 

• The window’s description of what portions of its ■window are visible should be up-to-date, 
and 

• The window should confine its activities to those ■visible areas. 

The first three of these requirements is met by locking; the last amounts to clipping the image 
the window will write to the bounds of its exposed area. All m-e handled implicitly by the access 
routines described in Accessing a Pixwin’s Pixels. Some clients will use those routines, but for 
efiRciency’s sake, lock explicitly around a body of screen access operations. 


3.4.1. Locking 

The pwjlock macro: 

pw_!ock(pw, r) 

struct pixwin ♦pw; 

struct rect ♦r; 

uses the lock routine pointed to by the window’s pw_elipops to acquire a lock for the user pro¬ 
cess that made this call. Pw addresses the pixwin to be used for the ouput; r is the rectangle in 
the window’s coordinate system that bounds the area to be affected. Pwjlock blocks if the lock 
is unavailable, for example, if another process currently has the display locked. 

Lock operations for a single pixwin may be nested; inner lock operations merely increment a 
count of locks outstanding, pwcdjockcount in the window’s pw_clipdata struct. Their affected 
rectangles must lie within the original lock’s. 
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A similar macro is: 

pw_unlock(pw) 

struct pixwin *pw; 

which decrements the lock count. If this brings it to 0, the lock is actually released. 

Since locks may be nested, it is possible for a client procedure to find itself especially in error 
handling with a lock which may require an indefinite number of unlocks. To handle this situa¬ 
tion cleanly, another routine is provided. The following macro sets pw's lockcount to 0 and 
release its lock: 

pwjreset(pw) 

struct pixwin *pw; 

Like pwjlock and pw_unloek, pwjock calls a routine addressed in the ptxwin's pixwin_clipopa 
struct, in this case the one addressed by pwcojreaet. 

Acquisition of a lock has the following effects: 

• If the cursor is in conflict with the affected rectangle, it is removed from the screen. While 
the screen is locked, the cursor will not be moved in such a way as to disrupt any screen 
accessing. 

• Access to the display is restricted to the process acquiring the lock. 

• Modification of the database that describes the positions of all the windows on the screen is 
prevented. 

• The id of the most recent clipping information for the window is retrieved, and compared 
with that stored in pweijelipid in the window’s pwjslipdata. If they differ, the routine 
addressed by pu}eo_getelipping is invoked, to make all the fields in pw_clipdata accurately 
describe the area which may be written into, 

• Once the correct clipping is in hand, the pwcd_ttate variable’s value determines how to set 
pw_opt, pw_opthandle, pw_opsz and pw_opay. This setting is done in anticipation of further 
screen access operations being done before a subsequent unlock. These values can often be 
set to bypass the pixwin software by going directly to the pixrect level. 

Locking is both moderately expensive as it involves two system calls, and capable of impacting 
other processes. Clients with a recognizable group of screen updates to do can gain noticeably 
by surrounding the group with lock - unlock brackets; then the locking overhead will only be 
incurred once. An example of such a group might be a line of text, or a series of vectors which 
have all been computed. 

While it has the screen locked, a process should not 

• do any significant computation unrelated to displaying its image; 

• invoke any system calls, including other I/O, which might cause it to block; or 

• invoke any pixwin calls except pw_unlock and those described in Aecetaing a Pixwin'a Pix- 
eh. In any case, the lock should not be held longer than about a quarter of a second, even 
following all these guidelines. 

As a deadlock resolution approach, when a display lock is held for more than 10 seconds, the 
lock is broken. However, the offending process is not notified by signal; the idea is that a pro¬ 
cess shouldn’t be aborted for this infraction. A message is displayed on the console. 
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3.4.2. Clipping 

Output to a window is clipped to the window’s pwed_clipping rectlist, this is a series of rectan¬ 
gles which, taken together, cover the valid area that this window may write to. There are two 
routines which set the piximn's clipping: 

pw_exp03ed(pw) 

struct pixwin ♦pw; 

pw_damaged(pw) 

struct pixwin *pw; 

Pv)_damaged is discussed in Damage, Pwjexpoaed is the normal routine for discovering what 
portion of a window is visible. It retrieves the rectUat describing that area into the piztwn’s 
pwed_clipping, and stores the id identifying it in pwed_clipid. It also stores its own address in 
the pizu'in’s pwco_getcl{pping, so that subsequent lock operations will get the correct area 
description. 

Clipping, even more than locking, should normally be left to the library output routines. For 
the intrepid, the strategy these routines follow is briefly sketched here; the rectliat data struc¬ 
tures and procedures in Appendix A are required reading. 

Some procedure will set the pixwm's pwcd_clipping so that it contains a reetUat describing the 
region which may be painted. This is done by a lock operation which makes a call through 
*pwco_getclipping, or an explicit call to one of pxv_open, pu)_donedamagedf pw_expoaed or 
pw_damaged. This rectliat is essentially a list of rectangular fragments which together cover the 
area of interest. As an image is generated, portions of it which lie outside the rectangle list 
must be masked off, and the remainder written to the window through a pizrect. 

The clipping aid pwcdjprmrtlti is set up to be a pizrect which clips for the entire rectangular 
area of the window. Any clipping using this pixrect must utilize the information in 
pwcd_ctipping to do the actual clipping to multiple rectangles. 

Pwcd_prl is set up to parallel each of the rectangles in pu!cd_clipping. Thus, if one draws to 
each of the pixrecta in this data structure, the image will be correctly clipped. Pwed_atate is set 
by examining the makeup of the pwcd_elipping. If pwcd_atate is PWCD_SINGLERECT, a pix¬ 
rect is set up in pwed_praingle also. When this case exists, after pw_lock and before puf_unloek, 
most screen accesses will directly access the pizrect level of software. Thus, in this common 
case, screen access is as fast in the window system as it is on the raw pizrect software outside of 
the window system. Also, pwcd_praingle is set up with a zero height and width pizrect when 
pw€d_atate is PWCD_NULL. 

As an escape, none of the pizrect setup described above takes place when pwcd_atate is 
PWCD_USERDEFtNE. This means that clipping is the responsibility of higher level software. 

A client may write to the display with an operation which specifies no clipping (op | 
PIX_DONTCLIP). This means that it is doing the clipping at a higher level. Note that clip¬ 
ping data is only valid during the time the client may write to the screen, that is when the 
window’s owner process holds a lock on the screen. If the clipping is done wrong, it is possible 
to damage another window’s image. 
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3.5. Accessing a Pixwin’s Pixels 

Procedures described in this section provide all the normal facilities for output to a window and 
should be used unless there are special circumstances. Each contains a call to the standard lock 
procedure, described in Locking. Each takes care of clipping to the rectliat in pw_clipping. Since 
the routines are used both for painting new material in a window and for repairing damage, 
they make no assumption about what clipping information should be gotten. Thus, there 
should be some previous call to either pw_opcn, pw_donedamagcd, pxvjcxposcd or pw_damaged, to 
initialize pwo_getcltpping correctly. 

The procedures described in this section will maintain the memory pixrect for a retained pixwin. 
That is, they check the window’s pw_prretatned, and if it is not null, perform their operation on 
that data in memory, as well as on the screen. 


3.5.1. Write Routines 

pw_write(pw, xd, yd, width, height, op, pr, xs, ys) 
struct pixwin *pw; 

int op, xd, yd, width, height, xs, ys; 

struct pixrect *pr; 

pw_writebackground(pw, xd, yd, width, height, op) 

Pixels are written to the pixwin pw in the rectangle defined by xd, yd, width, and height, using 
rastcrop function op (as defined in Conttructing Op Argumenta for Rop and Batchrop Pixrec- 
tops). They ^e taken from the rectangle with its origin at xt, ya in the source pixrect pointed 
to by pr. Pwjwritebackground simply supplies a null pr which indicates that an infinite source 
of pixels, all of which are set to zero, is used. The following draws a pixel of value at {x, y) in 
the addressed pixwin: 

pw_put(pw, X, y, value) 
struct pixwin fpw; 

int X, y, value; 

The next draws a vector of pixel value from (xO, yO) to (xl, yl) in the addressed pixwin using 
rasterop op: 

pw_vector(pw, xO, yO, xl, yl, op, value) 

struct pixwin *pw; 

int op, xO, yO, xl, yl, value; 

pwjreplrop(pw, xd, yd, width, height, op, pr, xs, ys) 
struct pixwin *pw; 

int op, xd, yd, width, height; 

struct pixrect *pr; 

int xs, ys; 

This procedure uses the indicated raster op function to replicate a pattern (found in the source 
pixrect) into a destination in a pixwin. For a full discussion of the semantics of this procedure, 
refer to the description of the equivalent procedure prjreplrop in Pixel Data and Operations. 
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The following two routines: 

pw_text(pw, X, y, op, font, s) 
struct pixwin *pw; 

int X, y, op; 

struct pixfont *font; 

char *8; 

pw_char(pw, x, y, op, font, c) 
struct pixwin *pw; 

int X, y, op; 

struct pixfont *font; 

char c; 

write a string of characters and a single character respectively, to a pixwin, using rasterop op as 
above. Pwjtext and pw_char are distinguished by their own coordinate system: the destination 
is given as the left edge and baseline of the first character. The left edge does not take into 
account any kerning (character position adjustment depending on its neighbors), so it is possible 
for a character to have some pixels to the left of the x>coordinate. The baseline is the y- 
coordinate of the lowest pixel of characters without descenders, ‘L’ or ‘o’ for example, so pixels 
will frequently occur both above and below the baseline in a string. Font may be NULL in 
which case the system font is used. 

The system font is the same as the font returned from pf_default. In addition, the system font 
is reference counted and shared between software packages. To get the system font call 
pw_pfsysopen: 

struct pixfont *pw_pfsysopen() 

When you are done with the system font call pwjpfsyscloser. 

pw_pfsysclose() 

Note: A font to be used in pwjtext is required to have the same pe_home.y and character height 
for all characters in the font. 

The following routine: 

pw_ttext(pw, x, y, op, font, s) 
struct pixwin *pw; 

int x, y, op; 

struct pixfont *font; 

char *8; , 

is just like pwjtext except that it writes transparent text. Transparent text writes the shape of 
the letters without disturbing the background behind it. This is most useful with color pixwins. 
Monochrome pixwins can use pwjtext and a PIX_SRC|PIX_DST op, which is faster. 

Applications such as displaying text perform the same operation on a number of pixrects in a 
fashion that is amenable to global optimization. The batchrop procedure is provided for these 
situations: 

pw_batchrop(pw, dx, dy, op, items, n) 
struct pixwin *pw; 

int dx, dy, op, n; 

struct batchitem items[ ]; 
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Pu’^bafchrop is exactly analogous to prjbatchrop described in Pixel Data and Operations. Refer 
ti e re for a detailed explanation of pwjbatchrop. 

Stencil ops are like raster ops except that the source pixrect is written through a stencil pixrect 
which functions as a spatial write enable mask. The indicated raster operation is applied only 
to destination pixels where the stencil pixrect is non-zero. Other destination pixels remain 
unchanged. 

nw_stencil(dpw, dx, dy, dw, dh, op, stpr, stx, sty, spr, sx, sy) 

I struct pixwin *dpw; 

struct pixrect *stpr, *spr; 

int dx,dy,dw,dh,op,8tx,8ty,8x,8y; 

Pw_steneil is exactly analogous to pr_steneil described in Pixel Data and Operations. Refer 
there for a detailed explanation of pw_jtencil. 


3.5.2. Read and Copy Routines 

The following routines use the window as a source of pixels. They may find themselves 
thwarted by trying to read from a portion of the pixwin which is hidden, and therefore has no 
pixels. When this happens, pw_fixup in the pixwin structure will be filled in by the system with 
the description of the source areas which could not be accessed. The client must then regen¬ 
erate this part of the image into the destination. Retained pixwina will always return rl_nttll in 
pw_fixup because the image is refreshed from pwjprretained. The following returns the value of 
the pixel at (x, ]/) in the addressed pixwin: 

pw_get(pw, X, y) 

struct pix^win *pw; 

int X, yj; 

Pixels are read from the pixwin into a pixrect by: 

pw_read(pr, xd, yd, width, height, op, pw, xs, ys) 
struct pixwin *pw; 

int op, xd, yd, width, height, xs, ys; 

struct pixrect *pr; 

Pixels are read from the rectangle defined by xs, ys, width, height, in the pixwin pointed to by 
pw, using rasterop function op. The pixels are stored in the rectangle with its origin at xd, yd in 
the pixrect pointed to by pr. 

Copy is used when both source and destination are pixwins; 

pw_copy(dpw, xd, yd, width, height, op, spw, xs, ys) 
struct pixwin *dpw, *8pw; 

int op, xd, yd, width, height, xs, ys; 

Note: Currently dpw and spw must be the same pixwin. 

3.5.3. Bitplane Control 

For pixwins on color display devices, one must be able to restrict access to certain bitplanes. 
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pw_putattributes(pw, planes) 
struct pixwin ♦pw; 

int ^planes; 

Planet is a bitplane access enable mask. Only those bits of the pixel corresponding to a 1 in the 
same bit position of *planet will be affected by pixwin operations. Pw_putattributet sets the 
access enable mask of pw. If the planet argument is NULL, that attribute value will not be writ¬ 
ten. 

Note: Use pw_putattributei with care; it changes the internal state of the pixwin until 
pw_putattributet is next called. Don’t forget to restore the internal state once through accessing 
in this special mode. 

pw_getattributes(pw, planes) 
struct pixwin *pw; 

int ’^planes; 

retrieves the value of the access enable mask into *planet. 


3.6. Damage 

When a portion of a client’s window becomes visible after having been hidden, it is damaged. 
This may arise from several causes. For instance, an overlaying window may have been 
removed, or the client’s window may have been stretched to give it more area. The client is 
notified that such a region exists by the signal SIQWINCH; this simply indicates that something 
about the window has changed in a fashion that probably requires repainting. It is possible that 
the window has shrunk, and no repainting of the image is required at all, but this is a degen¬ 
erate case. It is then the client’s responsibility to repair the damage by painting the appropriate 
pixels into that area. The following section describes how to do that. 

3.6.1. Handling a SlGWikCilt l^ignal 

There are several stages to handling a SIGWINCH. First, in almost all cases, the procedure that 
catches the signal should not immediately try to repair the damage indicated by the signal. 
Since the signal is a software interrupt, it may easily arrive at an inconvenient time, halfway 
through a window’s repaint for some normal cause, for instance. Consequently, the appropriate 
action in the signal handler is usually to set a flag which will be tested elsewhere. Conveniently, 
a SIGWINCH is like any other signal; it will break a process out of a telect system call, so it is 
possible to awaken a client that was blocked, and with a little investigation, discover the cause 
of the SIGWINCH. See the telect{2) system call and refer to the toot_teleet mechanism in Tool 
Processing tor an example of this approach. 

Once a process has discovered that a SIGWINCH has occurred and arrived at a state where it’s 
safe to do something about it, it must determine exactly what has changed, and respond 
appropriately. There are two general possibilities: the window may have changed size, and/or 
a portion of it may have been uncovered. 

Win^etsize (described in Window Manipulation) can be used to inquire the current dimensions 
of a window. The previous size must have been remembered, for instance from when the win¬ 
dow was created or last adjusted. These two sizes are compared to see if the size has changed. 
Upon noticing that its size has changed, a window containing other windows may wish to 
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rearrange the enclosed windows, for example, by expanding one or more windows to fill a newly 
opened space. 

Whether a size change occurred or not, the actual images on the screen must be fixed up. It is 
possible to simply repaint the whole window at this point — that will certainly repair any dam¬ 
aged areas — but this is often a bad idea because it typically does much more work than neces- 

sriry. 

Therefore, the window should retrieve the description of the damaged area, repair that damage, 
and inform the system that it has done so: The pw_damaged procedure: 

pwjdamaged{pw) 

struct pixwin *pw; 

is a procedure much like pw_cxpo»ed. It fills in pwcd_dipp%ng with a rectliat describing the area 
of interest, stores the id of that rectliat in the pizwin's opadata and in pwcd_damagedid as well. 
It also stores its own address in pwco_getclipping, so that a subsequent lock will check the 
correct rectliat. All the clippers arc set up too. Cotormap segment offset initialization is done, 
as described in Surface Preparation. 

Now is the time for the client to repaint its window ■—• or at least those portions covered by the 
damaged rectliat, if the regeneration is relatively expensive, that is if the window is large, or its 
contents complicated, it may be worth restricting the amount of repainting before the clipping 
that the rectliat will enforce. This means stepping through the rectangles of the rectliat, deter¬ 
mining for each what data contributed to its portion of the image, and reconstructing only that 
portion. See Appendix A for details about rectliata. 

For retained pixwins, the following call can be used to copy the image from the backup pixrect 
to the window: 

pw_repairretained(pw) 
struct pixwin *pw; 

When the image is repaired, the client should inform the window system with a call to: 

pw_donedam aged( pw) 
struct pixwin *pw; 

Pw_donedamaged allows the system to discard the rectliat describing this damage. It is possible 
that more damage will have accumulated by this time, and even that some areas will be 
repainted I more than once, but that will be rare. 

After calling pw_donedamaged, the pizu^tn describes the entire visible area of the window. 

A process which owns more than one window can receive a SIGWINCH for any of them, with no 
indication of which window generated it. The only solution is to fix up all windows. For¬ 
tunately, that should not be overly expensive, areas are completely and exactly specified by the 
returned value for pw_damaged. 

I 

3*7. Colormap Manipulation 

Pixwins pi'ovide an interface to a basic colormap sharing mechanism. Portions of the colormap, 
colormap tegmenta, are named and can be shared among cooperating processes. Use of a color- 
map segment, as opposed to the entire colormap, is essentially invisible to clients. Routines 
that access a pixwin’s pixels do not distinguish between windows which use colormap segments 
and those which use the entire colormap. 
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3.7.1. Initialization 

Pw_open and pw_region both create and return a pbewin. If a colormap segment is already 
defined for the window of the pixwin, this is the colormap segment used in the new pixwin. 
However, if the window has no colormap segment defined for it, a monochrome colormap seg¬ 
ment is setup for the pixwin by default. The default segment is defined in 
I utrf include! tunwindowj cm»_mono,h. 


3.7.2. Background and Foreground 

Every colormap segment has two distinguished values, its background and foreground. The 
background color is defined as the value at the first position of a colormap segment. The fore¬ 
ground color is defined as the value at the last position of a colormap segment (the colormap 
segment’s size minus 1). 

The foreground is important in terms of color/monochrome compatibility. Any source color, 
other than 0, that is written on a monochrome pixrect is translated to the foreground color. 

Pw_open and pw_region set the background and foreground of the returned pixwin to be those 
of the overall screen (see win_»ereenget). In addition, if the screen is defined as being inverted, 
the background and foreground are reversed. For reasons involving image blanking, invisible 
cursors, merged boundso'ies, cotor/monochrome compatibility, relative colormap segment place¬ 
ment, and so on, this pre-emption is vital to the overall integrity of color displays doing color- 
map sharing. Monochrome displays have many of these problems, although they are less severe 
than on color displays. 

Here are handy utilities to set two specific colormap segment entries: 

pw_reversevideo(pw, min, max) 
struct pixwin *pw; 

int min, maic; 

pw_blackonwhite(pw, min, max) 
struct pixwin *pw; 

int min, max; 

pw_whiteonblack(pw, min, max) 
struct pixwin *pw; 

int min, max; 

Min and max are the first and last entries in the colormap, respectively. If min is the back¬ 
ground and max is the foreground and pw is a color pixwin, these calls do nothing. 

3.7.3. A New Colormap Segment 

For 3 different colormap segment for a pixwin, a new name must be created. If the colormap 
segment’s usage is to be static in nature, by all means try to use a shared colormap segment 
definition. The colormap segment definitions that could be shared with other windows are in 
f uerjinclude!BuntuindowfcmB_*.h. These are cmB.h, cmB_rgb.h, cmB_graga.h, cmB_mono.h, and 
cmBjrainbow.h. Even if no other program shares your colormap segment, at least multiple 
instances of your program could share it. Remember that colormap entries are scarce. 
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If tMs new colormap segment should not be shared by another window then the name should be 
unique. A common way to generate a unique name is to append your process id to a more 
meaningful string that describes the usage of the colormap segment. 

pw_setcmsname(pw, cmsname) 
struct pixwin *pw; 

char cmsname[20]; 

Cmtname is the name that pw will call its window’s colormap segment. Just setting the name 
has the effect of resetting the colormap segment to a NULL entry. Usually, the very next call 
after pw_»etemBname should be pw_puteolormap as described in the next section. 

Colormap segments are associated with windows, not pixwins. Each window can have only one 
colormap segment. Pixwins provide an interface for managing that one colormap segment. 
Since more than one pixwin may exist per window, care should be taken to avoid changing the 
colormap segment definition out from underneath another pixwin on the same window. 

pw_getcmsname(pw, cmsname) 
struct pixwin '•'pw; 

char cmsname[20]; 

The colormap segment name of pw is copied into cmsname. 

3.7.4. Colormap Access 

pw_putcolormap(pw, index, count, red, green, blue) 
struct pixwin *pw; 

int index, count; 

unsigned char red (j, green[ ], blue[ ]; 

The count elements of the pixwin’s colormap segment starting at index (zero relative) are loaded 
with the first count values in the three arrays. A colormap has three components each indexed 
by a given pixel value to produce an RGB color. Monochrome pixwins assume red equals green 
equals blue. Pixrects of depth 8 have colormaps with 256 (2 to the eighth) entries. Background 
and foreground values are forced to the values defined by the screen. 

pw_getcolormap(pw, index, count, red, green, blue) 
struct pixwin *|>w; 

int index, count; 

unsigned char red [ j, green[ ], blue[ ]; 

finds out the state of the colormap segment. The arguments are analogous to those of 
pw^uteolormap. 

The utility: 

P'w_cyclecolormap(pw, cycles, index, count) 
struct pixwin '•'pw; 

int cycles, index, count; 

is handy for taking a portion of pw's colormap segment, starting at index for count entries, and 
rotating those entries among themselves for cycles. A cycle is defined as the count shifts it takes 
one entry to move through every position once. 
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3.7.5. Surface Preparation 

In order for a client to ignore the offset of his colormap segment the image of the pixwin must 
be initialized to the value of the offset. This turface preparation is done automatically by 
pixwins under the following circumstances: 

• The routine pv)_damaged does surface preparation on the area of the pixwin that is dam¬ 
aged. 

• The routine pw_putcolormap does surface preparation over the entire exposed portion of a 
pixwin if a new colormap segment is being loaded for the first time. 

For monochrome displays, nothing is done during surface preparation. For color displays, when 
the surface is prepared, the low order bits (colormap segment size minus 1) are not modified. 
This mean that surface preparation does not clear the image. Initialization of the image (often 
clearing) is still the responsibility of client code. 

There is a case in which surface preparation must be done explicitly by client code. When win¬ 
dow boundaries are knowingly violated (see win_grabio), as in the case of pop-up menus, the fol¬ 
lowing procedure must be called to prepare each rectangle on the screen that is to be written 
upon: 

pw jrepare8urface(pw, rect) 
struct pixwin *pw; 

struct rect *r; 

Reet is relative to pw’s coordinate system. Most commonly, a saved copy of the area to be writ¬ 
ten is made so that it can be restored later. 
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Window Manipulation 


This chapter describes the aunwindow facilities for creating, positioning, and controlling win- 
do^Sc It continues the discussion begun in Overlapped Windows: Imaging Facilities, on the 
snnwindow level that allows displaying images on windows which may be overlapped. 

The structure that underlies the operations described in this chapter is maintained within the 
window system, and is accessible to the client only through system calls and their procedural 
envelopes, it will not be described here. The window is presented to the client as a device; it is 
represented, like other devices, by a file descriptor returned by open. It is manipulated by other 
I/O calls, such as select, read, ioctl, and close. Write to a window is not defined, since all the 
facilities of the previous chapter on Overlapped Windows: Imaging Facilities are required to 
display output on a window. 

The header file fusrf include!snnwindowfwindowjis.h header files needed to work at 

this level of the window system. 

4.1. Window Data 

The information about a window maintained by the window system includes: 

• two rectangles which refer to alternative sizes and positions for the window on the screen; 

• a series of links that describe the window’s position in a hierarchical database, which deter¬ 
mines its overlapping relationships to other windows; 

• clipping information used in the processing described in Overlapped Windows: Imaging Factl- 
ities; 

m the image used to track the mouse when it is in the window; 

• the id of the process which should receive SIGWINCH signals for the window (this is the 
owner process); 

• a mask that indicates what user input actions the window should be notified of; 

• another window, which is given any Input events that this window does not use; and 

• 32 bits of data private to the window client. 

4.2. Window CreaiEion, Destruction, and Reference 

As mentioned above, windows are devices. As such, they are special files in the /dev directory 
with names of the form f devf winn'\ where n is a decimal number. A window is created by 
opening one of these devices, and the window name is simply the filename of the opened device. 
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4.2.1. A New Window 

The first process to open a window becomes its ovmer. A process can obtain a window it is 
guaranteed to own by calling: 

ini win_getnewwindow() 

This finds the first unopened window, opens it, and returns a file descriptor which refers to it. 
If none can be found, it returns -1. A file descriptor, often called the windowfd, is the usual 
handle for a window within the process that opened it. 

When a process is finished with a window, it may close it. This is the standard c/o«c(3) system 
call with the window’s file descriptor as argument. As with other file descriptors, a window left 
open when its owning process terminates will be closed automatically by the operating system. 

Another procedure is most appropriately described at this point, although in fact clients will 
have little use for it. To find the next available window, u>m_jjctnewivindow uses: 

int win_nextfree(fd) 
int fd; 

where fd is a file descriptor it got by opening / dev/tvinO. The return value is a unndow number, 
as described in Referencet to Windows below; a return value of WIN_NULLLINK indicates 
there is no available unopened window. 


4.2*2* An Existing Window 

It is possible for more than one process to have a window open at the same time; Providing for 
Naive Programs presents one plausible scenario for using this capability. The window will 
remain open until all processes which opened it have closed it. The coordination required when 
several processes have the same window open is described in Providing for Naive Programs. 


4*2*3. References to Windows 

Within the process which created a window, the usual handle on that window is the file descrip> 
tor returned by open and win_getnewwindow. Outside that process, the file descriptor is not 
valid; one of two other forms must be used. One form is the window name (e.g., /dev/winl2); 
the other form is the window number, which corresponds to the numeric component of the win¬ 
dow name. Both of these references are valid across process boundaries. The window number will 
appear in several contexts below. 

Procedures are supplied for switching the various window identifiers back and forth. 
Win_numbertoname stores the filename for the window whose number is winnumber into the 
buffer addressed by name: 

win_numbertoname(winnumber, name) 
int winnumber; 

char *name; 

Name should be WIN_NAMESIZE long as should all the name buffers in this section. 
Win_nametonumber returns the window number of the window whose name is passed in name: 

int win_iiametonumber(name) 
char *Dame; 
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Given a window file descriptor, wm_Jdtoname stores the corresponding device name into the 
buffer addressed by name: 

win_fdtoname(windowfd, name) 
int windowfd; 

char *name; 

The following returns the window number for the window whose file descriptor is windowfd: 

int win_fdtonumber(windowfd) 
int windowfd; 


4.3. Window Geometry 

Once a window has been opened, its size and position may be set. The same routines used for 
this purpose are also helpful for adjusting the screen positions of a window at other times, when 
user-interface actions indicate that it is to be moved or stretched, for instance. The basic pro¬ 
cedures are: 

win_getrect(windowfd, rect) 
int windowfd; 

■truct rect ■^rect; 

wln^ct8ize(windowfd, rect) 
int windowfd; 

struct rect *rect; 

short win_gethcight(windowfd) 
int windowfd; 

short win_gctwidth(windowfd) 
int windowfd; 

Win_getrect stores the rectangle of the window whose file descriptor is the first argument into 
the rect addressed by the second argument; the origin is relative to that window’s parent. Set¬ 
ting Window Linkt explains what is meant by a window’s “parent.” 

Win_geUize is similar, but the rectangle is self-relative — that is, the origin is (0,0). 

Win^ethdght and win_getwidth return the single requested dimension for the indicated window. 
VVin_setreet copies the rect argument’s data into the rect of the indicated window: 

win_setrcct(windowfd, rect) 

Int windowfd; 

struct rect *rect; 

This changes its size and/or position on the screen. The coordinates are in the coordinate sys¬ 
tem of the window’s parent. 
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win_get8avcdrect(windowfd, rect) 
int windowfd; 

struct rect *rect; 

win_setsavedrect(windowfd, rect) 
int windowfd; 

struct rect ^rect; 

A window may have an alternate site and location; this facility is useful for teens, for example 
(see Full Screen Aecese). The alternate rectangle may be read with mn^eUavedrect, and writ¬ 
ten with wi'n_seteavedreet. As with unn_setreet and win^eetreet, the coordinates are relative to 
the window’s parent. 

4.4. The Window Hierarchy 

Position in the window database determines the nesting relationships of windows, and therefore 
their overlapping and obscuring relationships. Once a window has been opened and its size set, 
the next step in creating a window is to define its relationship to the other windows in the sys¬ 
tem. This is done by setting links to its neighbors, and inserting it into the window database. 


4.4.1. Setting Window Links 

The window database is a strict hierarchy. Every window (except the root) has a parent; it also 
has 0 or more eiblinge and children. In the terminology of a family tree, age corresponds to 
depth in the layering of windows on the screen: parents underlie their offspring, and older win¬ 
dows underlie younger siblings which intersect them on the display. Parents also enclose their 
children, which means that any portion of a child’s image that is not within its parent’s rectan¬ 
gle is clipped. Depth determines overlapping behavior: the uppermost image for any point on 
the screen is the one that gets displayed. Every window has links to its parent, its older and 
younger siblings, and to its oldest and youngest children. 

Windows may exist outside the structure which is being displayed on a screen; they are in this 
state as they are being set up, for instance. 

The links from a window to its neighbors are identified by link eeleetors; the value of a link is a 
window number. An appropriate analogy is to consider the link selector as an array index, and 
the associated window number as the value of the indexed element. To accommodate different 
viewpoints on the structure there are two sets of equivalent selectors defined for the links: 

WL_PARENT == WL_ENCL0SING 

WL.OLDERSIB —= WL.COVERED 

WL_YOUNGERSIB ~ WL_^COVERING 

WL.OLDESTCHILD ==• WL30TT0MCHILD 

WL_YOUNGESTCH!LD —— WL^TOPCHILD 

A link which has no corresponding window, a child link of a “leaf’ window, for instance, has 
the value WIN_NULLLINK. 

When a window is first created, all its links are null. Before it can be used for anything, at least 
the parent link must be set. If the window is to be attached to any siblings, those links should 

be set in the window as well. The individual links of a window may be inspected and changed 

by the following procedures. 
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Wm_^eiltnk returns a window number. 

int win_getlink(windowfd, linkjselector) 
int windowfd, link_selector; 

This number is the value of the selected link for the window associated with windowfd. 

win_8stlmk(windowfd, linkjselector, value) 
int windowfd, link_selector, value; 

V/in_«etlmk sets the selected link in the indicated window to be value, which should be another 
window number. The actual window number to be supplied may come from one of several 
sources: if the window is one of a related group, all created in the same process, file descriptors 
will be available for the other windows. Their window numbers may be derived from the file 
descriptors via wm_fdtonumber. The window number for the parent of a new window or group 
of windows is not immediately obvious, however. The solution is a convention that the 
WINDOWJPARENT environment parameter will be set to the filename of the parent. See 
Paesing Parameters to a Tool for an example of this environment parameter’s usage. 

4.4.2. Activating the Window 

Once a window’s links have all been defined, the window is inserted into the tree of windows 
and attached to its neighbors by a call to 

w in_insert( w indowfd) 
int windowfd; 

This call causes the window to be inserted into the tree, and all its neighbors to be modified to 
point to it. This is the point at which the window becomes available for display on the screen. 

Every window should be inserted after its rectangle(s) and link structure have been set, but the 
insertion need not be immediate: if a subtree of windows is being defined, it is appropriate to 
create the window at the root of this subtree, create and insert all of its descendants, and then, 
when the subtree is fully defined, insert its root window. This activates the whole subtree in a 
single action, which typically will result in a cleaner display interaction. 

Once a window has been inserted in the window database, it is available for input and output. 
At this point, it Is appropriate to call pw_open and access the screen. 

4.4.3. Modifying Wiildow Relationships 

Windows may be rearranged in the tree. This will change their overlapping relationships. For 
instance, to bring a window to the top of the heap, it should be moved to the “youngest” posi¬ 
tion among its siblings. And to guarantee that it is at the top of the display heap, each of its 
ancestors must likewise be the youngest child of its parent. 

To accomplish such a modification, the window should first be removed: 

w in_remove( w indowfd) 
int windowfd; 

After the window has been removed from the tree, it is safe to modify its links, and then rein¬ 
sert it. 
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A process doing multiple window tree modifications should lock the window tree before it 
begins. This prevents any other process from performing a conflicting modification. This is 
done with a call to: 

w in_lockdata(w indowfd) 
int windowfd; 

After all the modifications have been made and the windows reinserted^ the lock is released with 
a call to: 

win_unlockdata(windowfd) 
int windowfd; 

Most routines described in this chapter, including the four above, will block temporarily, if 
another process either has the database locked, or is writing to the screen, and the window 
adjustment has the possibility of conflicting with the window that is being written. 

As a method of deadlock resolution, SIGXCPU is sent to a process that spends more that 10 
seconds of real time inside a window data lock, and the lock is broken. 


4.5. User Data 

Each window has 32 bits of uninterpreted client data associated with it. This is not touched by 
the basic window system; typically the client uses it to store flags. Higher levels of the system 
may implement minimal inter^window status-sharing through this facility. This data is manipu¬ 
lated with the following procedures: 

win_getu8erflags(windowfd) 

Int windowfd; 

win_setuserflags(windowfd, flags) 
int windowfd; 

int flags; 

winj5etuserflag(windowfd, flag, value) 
int windowfd; 

int flag; 

int value; 

Win^etuterflags returns the user data. Win_»ettuerflags stores its flags argument into the win¬ 
dow struct. Wtnjsetuserflag uses flag as a mask to select one or more flags in the data word, 
and sets the selected flags on or off as value is TRUE or FALSE. 


4.6. Minimal-Repaint Support 

This section has strong connections to the preceding chapter and to Appendix A on Reels and 
Reetlists. Readers should refer to both from here. 

Moving windows about on the screen may involve repainting large portions of their image in 
new places. Often, the existing image can be copied to the new location, saving the cost of 
regenerating it. Two procedures are provided to support this function: 

win_computeclipping(windowfd) 
int windowfd; 


4-6 


Revision D of 7 January 1984 








SucWiidows Reference Manual 


Window Manipulation 


causes the window system to recompute the exposed and damaged rectlists for the windows on 
the screen while withholding the SIGWINCH that will tell each owner to repair damage. 

Win_parti cdrepair. 

win_j>artialrepair(windowfd, r) 
int windowfd; 

struct rect *r; 


tells the window system to remove the rectangle r from the damaged area for the window 
identified hy windowfd. This operation is a no-op if windowfd has damage accumulated from a 
previous window database change, but has not told the window system that it has repaired that 

damage. 

Any window manager can use these facilities etccording to the following strategy: 

• The old exposed areas for the affected windows are retrieved and cached, (pw^exposed) 

a The window database is locked and manipulated to accomplish the rearrangement. 
{wmjlockdata, winjremove, win_setlink, win_setrect, win_insert ...) 

• The new area is computed, retrieved, and intersected with the old. (win_computeclipp{ng, 
pw_exposed, rl^intersection) 

• Pixels in the intersection are copied, and those arezus are removed from the subject window’s 
damaged area. (pw__lock, pr^copy, win^artialrepair) 

• The window database is unlocked, and any windows still damaged get the signals informing 
them of the reduced damage which must be repaired. 

4.7. Multiple Screens 

Multiple displays may be simultaneously attached to a workstation, and clients may want win¬ 
dows on all of them. Therefore, the window database is a forest, with one tree of windows for 
each display. Thus, there is no overlapping of window trees that belong to different screens. 
For displays that share the same mouse device, the physical arrangement of the displays can be 
passed to the window system, and the mouse cursor will pass from one screen to the next as 
though they were continuous. 
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struct singlecolor { 

u char red, green, blue; 

}; 

struct screen { 

char scr_rootname[SCR_NAMESIZE]; 

char scr_kbdname(SCR_NAMESIZE]; 

char scr_nisnanie[SCR_NAMESIZE]; 

char 8cr_fbname|SCR_NAMESIZEl; 

struct singlecolor scr_foreground; 

struct singlcolor scr^^kgi^ound; 

int 8cr_flags; 

struct rect 8cr_rect; 

}; 

#define SCR.NAMESIZE 20 

#define SCR.SWITCHBKGRDFRGRD 0x1 

The tcrcen structure describes a client’s notion of the display screen. There are also fields indi¬ 
cating the input devices associated with the screen. Scrjrootname is the device name of the 
window ivhich is at the base of the window display tree for the screen; the default is 
'^fdevjwmff'. Scr_kbdname is the device name of the keyboard associated with the screen; the 
default is "fdev/kbd". 5cr_m«ndme is the device name of the mouse associated with the screen; 
the default is f devf moutc". Ser_Jhname is the device name of the frame buffer on which the 
screen is displayed; the default is “fdev//b”. Scr_kbdname, tcr_msname and 8cr_fbname can 
have the string “NONE" if no device of the corresponding type is to be associated with the 
screen. Scr_forcground is three RGB color values that define the foreground color used on the 
frame buffer; the default is {colormap size-1, colormap size-1, colormap size-1}. 
Scr_bttckground is three RGB color values that define the background color used on the frame 
buffer; the default is {0, 0, 0}. The default values of the background and foreground yield a 
black on white image. Scr_flaga contains boolean flags; the default is 0. 
SCR_3WITCHBKGRDFRGRD is a flag that directs any client of the background and fore¬ 
ground data to switch their positions, thus providing a video reversed image (usually yielding a 
white on black image). Serjreet is tlie size and position of the screen on the frame buffer; the 
default is the entire frame buffer surface. 

W$n_8creenneHr. 

int win_iicreennew (screen) 
struei screen ’•'screen; 

opens and returns a window file descriptor for a root window. This new root window resides on 
the new screen which was defined by the specifications of *aereen. Any zeroed field in *acreen 
tells win_icreennew to use the default value for that field (see above for defaults). Also, see the 
description of u/in_int^«creen/romar[ 7 v below. If -1 is returned, an error message is displayed to 
indicate that there was some problem creating the screen. 

There can be as many screens as there are frame buffers on your machine and dtop devices 
configured into your kernel. The kernel calls screen instances desktops or dtops. 

Wtn_screenget: 
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•wiii_8creenget(windowfd, screen) 

Int windowfd; 

struct screen ^screen; 

fills in the addressed struct screen with information for the screen with which the window indi¬ 
cated by windowfd Is associated. 

Winjsereen destroy, 

w in_screende8troy( windowfd) 
int windowfd; 

causes each window owner process (except the invoking process) on the screen associated with 
windowfd to be sent a SIGTERM signal. 

Winjsetsereenpositions informs the window system of the logical layout of multiple screens: 

win_8etscreenpositions(windowfd, neighbors) 

int windowfd, neighbor8(SCR_POSITIONSj; 

#dcfine SCR_NORTH 0 

#define SCR.EAST 1 

#define SCR_SOUTH 2 

#definc SCR.WEST 3 

#definc SCR^POSITIONS 4 

This enabl~3 the cursor to cross to the appropriate screen. Windowfd^i window is the root for 
its screen; the four slots in neighbors should be filled in with the window numbers of the root 
windows for the screens in the corresponding positions. No diagonal neighbors are defined, since 
they are not strictly neighbors. 

Winjetscreenpositions fills in neighbors with windowfis screen’s neighbors: 

win_getscreettpositions(windowfd, neighbors) 

int windowfd, neighbors (SCR_POSITIONS]; 

Win_setkbd: 

int win_setkbd(windowfd, screen) 
int windowfd; 

struct screen * screen; 

is used to change the keyboard associated with windowfd's screen. Only the data relative to the 
keyboard is used (i.e., sereen-‘> scr_kbdnome). 

Win_setmsi 

int win_setms(windowfd, screen) 
int windowfd; 

struct screen *screen; 

is used to change the mouse associated with windowfd's screen. Only the data relative to the 
mouse is used (i.e., screen-> serjmsname). 

Winjinitscreenfromargv: 

int win_initscreenfromargv(screen, argv) 
struct screen * screen; 

char ♦♦argv; 
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can be used to do a standard command line parse of argv into *»ereen. *Screen is first eeroed. 
The syntax is: 

[-d display device] [-m mouse device] (-k keyboard device] [-1] J-f red green Wue] [-b red green blue] 
See <unfoo/«(I) for semantics and details. 


4.8. Cursor and Mouse Manipulations 

This section describes the interface to the mouse and the cursor that follows the mouse. Both 
of which are maintained by the window system internals. 


4.8.1. Cursors 

The cursor is the image which tracks the mouse on the screen: 

struct cursor { 

short cur_xhot, curjrhot; 

int cur_function; 

struct pixrect *cur_8hape; 

}; 

#define CUR_MAXIMAGEWORDS16 

Cur_shape points to a memory pixrect which holds the actual image for the cursor. The win¬ 
dow system supports a ear_sh<ipe.pr_data~'>-md_im<ige up to CUR_MAXIMAGEWORDS words. 

The “hot spot" defined by (c«r_*Aot, cur^hot) associates the cursor image, which has height 
and width, with the mouse position, which is a single point on the screen. The hot spot gives 
the mouse position an offset from the upper-left corner of the cursor image. 

Most cursors have a hot spot whose position is dictated by the image shape, the tip of an arrow, 
the center of a bullseye, the center of a cross-hair. Cursors can also be used as a status feed¬ 
back mechanism, an hourglass to indicate that some processing is occurring for instance. This 
type of cursor should have the hot spot located in the middle of its image so the user has a 
definite spot for pointing and does not have to guess where the hot spot is. 

The function indicated by cur_function is a rasterop (as described in Constructing Op Argu¬ 
ments for Rop and Batehrop Pixreetops), which will be used to paint the cursor. 
PIX_SRC I PIX_DST is generally effective on light backgrounds, for example in text, but invisi¬ 
ble over solid black. P1X„SRC * PIX_DST is a reasonable compromise over many different 
backgrounds, although it does poorly over a gray pattern. 

win_getcursor(windowfd, cursor) 

Int windowfd; 

struct cursor *cursor; 

stores a copy of the cursor that is currently being used on the screen into the buffer addressed 
by cursor. 

Win_s€tcursor: 

win_setcursor(windowfd, cursor) 
int windowfd; 

struct cursor *cursor; 
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sets the cursor and function that will be used whenever the mouse position is within the indi¬ 
cated window. 

If a window process does not want a cursor displayed, the appropriate mechanism is to set the 
cursor to one whose dimensions are both 0. 


4.8.2. Mouse Position 

Determining the mouse's current position is treated under Input to Application Programs. We 
note here that the standard procedure for a process to track the mouse is to arrange to receive 
an input event every time the mouse moves; and in fact, the mouse position is passed with every 
user input s window receives. 

The mouse position can be reset under program control; that is, the cursor can be moved on the 
screen, and the position that is given for the mouse in input events can be reset without the 
mouse on the table top being physically moved: 

win_setmou8eposition(windowfd, x, y) 
int windowfd, x, y; 

puts the mouse position at (x, p) in the coordinate system of the window indicated by windowfd. 
The result is a jump from the previous position to the new one without touching any points 
between. Input events occasioned by the move, window entry and exit and cursor changes, will 
be generated. This fztcility should be used with restraint, as users are likely to lose a cursor that 
moves independently of their control. 

Occasionally it is necessary to discover which window underlies the cursor, usually because a 
window is handling input for all its children. The procedure used for this purpose is: 

int win_^ndintersect(windowfd, x, y) 
int windowfd, x, y; 

where windowfd is the calling window's file descriptor, and (x, p) define a screen position in that 
window’s coordinate space. The returned value is a window number. X and p may lie outside 
the bounds of the window. 

4.9. Providing for Naive Programs 

There is a large class of applications that are relatively unsophisticated about the window sys¬ 
tem, but want to run in windows anyway. For example, a simple-minded graphics program 
may want a window in which to run, but doesn’t want to know about all the details of creating 
and positioning it. This section describes a way of allowing for these applications. 


4.9.1. Which Window to Use 

SunWindows defines fen important environment parameter, WINDOW_GFX. By convention, 
WINDOW_GFX is set to a string that is the device name of a window in which graphics pro¬ 
grams should be run. This window is already opened and installed in the window tree. Rou¬ 
tines exist to read and write this parameter: 
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int we_getgfxwindow(nanie) 
char *name 

we_8etgfxwindow(nanie) 
char *naine 

We_getgfxwindow returns a non-zero value if it cannot find a value. 


4.0.2. The Blanket Window 

A good way to take over an existing window is to create a new window that becomes attached 
to and covers the existing window. Such a covering window is called a blanket window. The 
covered window will be called the parent window in this subsection because of its window tree 
relationship with a blanket window. Note: It’s a bad idea to take over an existing window using 
win_9etowner. 

Using the parent window name from the environment parameter WINDOW_GFX (described 
above), open (2) the parent window. Get a new window to be used as the blanket window using 
w{n_getnewwindaw. Now call: 

int winjlnsertblanket(blanketfd, parentfd) 
int blanketfd, parentfd; 

A non-zero return value indicates success. As the parent window changes size and position the 
blanket window will automatically cover the parent. 

To remove the blanket window from on top of the parent window call: 

win_removeblanket(blanketfd) 
int blanketfd; 

If the process that created the blanket window dies before mnjremoveblanket can be called, the 
blanket window will automatically be removed and destroyed upon automatic closure of the 
window device. This automatic closure happens because the only open file descriptor on it will 
be in the creating process. 

A non-zero return value from win_ttblanket indicates that blanketfd is indeed a blanket window. 

int win_i8btanket(blanketfd) 
int blanketfd; 


4,10. Window Ownership 

Note: Do not use the two routines in this section for temporarily taking over another window. 
These routines are included for backwards compatibility reasons. 

SIGWINCH signals are directed to the process that otvna the window, the owner normally being 
the process that created the window, The following procedures may read from and write to the 
window: 
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iiat win_getowner(wmdowfd) 
int windowfd; 

■win_setowner(windowfd, pid) 
int windowfd, pid; 

\yin_£etowner returns the process id of the indicated window owner. If the owner doesn’t exist, 
itro io returned. Wtn_»etowner makes the process identified by pid the owner of the window 
indicated by mndowfd. Wm_tetowner causes a SIGWINOH to be sent to the new owner. 

4.11* Error Handling 

Except as explicitly noted, the procedures described in this section do not return error codes. 
The standard error reporting mechanism inside the $unwindow library is to call a procedure that 
displays a message, typically identifying the ioett call that detected the error. After the message 
display, the calling process resumes execution. 

This default error handling routine may be replaced by calling: 

int (*win_errorhandler(win_error)){) 

int (*win_error)(); 

The winjerr or handier procedure takes the address of one procedure, the new error handler, as 
an argument and returns the address of another procedure, the old error handler, as a result. 
Any error handler procedure should be a function that returns an int. 

win_error(errnum, winopnum) 
int errnum, winopnum; 

Errnum will be -1 indicating that the actual error number is found in the global errno. Winop¬ 
num is the ioctl number that defines the window operation that generated the error. See Error 
Menage Decoding in Programming Notea in the appendix. 
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Chapter 5 


Input to Application Programs 


This chapter continues the description of the sunwindow level of the Sun window system. Here 
we discuss how user input is made available to application programs. Unless otherwise noted, 
the structures and procedures discussed in this section are found in the header file 
fiitr/ include! tHnwindowj winjinput.h. 

The window system provides facilities which meet two distinct needs regarding input to an 
application program: 

• A uniform interface to multiple input devices allows programs to deal with varying key¬ 
boards and positioning devices, ignoring complexities due to facilities which the programs 
do not use. 

• Several different keyboards are available with Sun systems; they differ in the number and 
arrangement of keys. At a minimum, some clients will require ASCn characters, one per 
keystroke. More sophisticated clients will assign special values to non-standard keys (such 
as “META” characters in the range 0x80 and above). Some clients will assign functions to 
particular keys on the keyboard, and will distinguish key-down from key-up events. 

• The standard positioning device on a Sun is the mouse, which reports a location and the 
state of three buttons. Alternatively, some clients may use a tablet and stylus, or in place 
of the stylus, a “puck” with as many as 10 buttons on it. 

• In some client systems, the time between input events is significant; for example, when 
smoothing a user’s stylus trace, or assigning special meaning to multiple clicks of a button 
within a short period. 

The window system allows clients with only the simplest requirements to ignore all the compli¬ 
cations, while providing more sophisticated clients the facilities they require. The mechanism 
for accomplishing this is called the virtual input device. This mechanism with its input events is 
described in Virtual Input Device. 

• The second major section of this chapter describes how user inputs are collected from multi¬ 
ple sources, serialized, and distributed among multiple consumers. Multiple clients are able 
to accept inputs concurrently, and a slow consumer does not affect other clients’ ability to 
receive their inputs. Type-ahead and mouse-ahead are fully supported. 

• Client programs operate under the illusion that they have the user’s full attention, leav¬ 
ing the window system to handle the multiplexing. Therefore, a client sees precisely 
those input events that the user has directed to that application. 

* Conversely, the client may require inputs from multiple devices, where the exact 
sequences across all those devices is significant. The order of mouse and function key 
events is likely to be significant, for instance. This is provided for via a single unified 
input stream, rather than requiring polling of multiple streams, which would be 
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unacceptable in a multi'processed environment. 

• The distribution of input events takes into account the window’s indication of what 
events it is prepared to handle; other events are redirected, allowing a division of labor 
among the various components of a system. 


6.1. The Virtual Input Device 

This section describes the virtual device which generates user input, and how the input is 
presented to the client process. The device appears as an extended keyboard, different from 
existing keyboards, but incorporating the common features of most of them. It also incor' 
porates a locator which indicates a screen position, and a clock which reports a time in seconds 
and microseconds. 

5.1.1. Uniform Input Events 

Each user action generates an input event, which is reported in a uniform format regardless of 
the event. An event is reported in the following struct: 

struct inputevent { 


short 

ie_code; 

short 

ie_flags; 

short 

iejihiftmask; 

short 

iejocx; 

short 

iejocy; 

struct 

timeval iejime; 


}; 

Ie_eode identifies the source of the event, as a switch position on a Virtual Input Device. The 
exact definition of the codes is given in Event Cedes. In general, the input events fall into one of 
three classes: events that generate a single ASCII character; events related to locator motion and 
window geometry; and events identified with invocation of a special function, usually involving 
the depression or release of a single special button on the mouse or keyboard. These classes are 
known as ASCII, pseudo, and function events, respectively. 

The information provided by the code in ie_eode is interpreted according to event flags in 
ie_fiags. (See Event Flags below.) 

The remaining elements of the struct provide general status information which may be useful on 
any event: 

iejthijtmask is used to report the state of certain shift-keys that is, to modify the meaning of 
other events. 

iejocx and 

ie_/ocy provide the position of the locator in the window’s coordinate system at the time 
the event occurred. 

iejtime provides a timestamp for the event, in the format of a system timeval, as defined 
in /usrf include!sysftime.h. 


5-2 


Revision D of 7 January 1984 





SunWindows Reference Manual 


Input to Application Programs 


5.1.2. Event Codes 

Rveut codes can take on any value in the range from 0 to 65535 inclusive. Of the codes defined 
in the header file, 256 are assigned to the ASCn event class and the other 128 are partitioned 
bet'ween the pseudo and function event classes. The following constants define the number of 
codes and the first and last code in the latter two classes: 

#de£ne VKEY.CODES 128 

#define VKEY.FIRST 32512 

#define VKEY_LAST VKEY_FIRST+ VKEY_CODES-l 

5.1.2.1. ASCn Events 

The event codes in the range 0 to 511 inclusive are assigned to the ASCII event class. This class 
is further sub-divided: 

#define ASCII_FIRST 0 
#define ASCIl.LAST 127 

In particular, striking a key which has an obvious ASCII meaning causes the Virtual Input Device 
to enqueue for the client an event whose code is the 7-bit ASCII character corresponding to that 
key. Such a key with an obvious ASCII meaning is one in the main typing array labelled with a 
single letter of the alphabet. This is independent of the physical keyboard actually used. A 
slight complication occurs because of the presence of both upper- and lower-case characters in 
ASCII: if the user “shifts” the physical keyboard by depressing the CAPS-LOCK, SHIFT-LOCK, 
or SHIFT key the ie_eode contains the shifted ASCII character corresponding to the struck key. 

For physical keystations that are mapped to cursor control keys, the current implementation 
transmits a series of events with codes that correspond to the ANSI X3.64 7-bit ASCII encoding 
for the cursor control function. For physical keystations that are mapped to function keys, the 
current implementation transmits a series of events with codes that correspond to an ANSI X3.64 
user-definable escape sequence. For further details, see kbd{S). 

#define META.FIRST 128 
#define META_LAST 255 

Event codes from 128 to 255 inclusive are generated when the client has META translation 
enabled and the user strikes a key that would generate a 7-bit ASCII code while the META key 
is also depressed. In this case, the event code is the 7-bit ASCII code added to META_FIRST. 

5.1.2.2. Function Events 

Event codes in the function class correspond to button strikes that do not result in generation 
of an event code in the ASCII class. 

In the function class are the event codes associated with locator buttons: 

^define BUT(i) 

A physical locator often has up to 10 buttons connected to it. Alternatively, even though the 
physical locator does not have any buttons physically available on it, it may have buttons on 
another device assigned to it. A light pen is an example of such a locator. In either case, each of 
the n buttons (where 0 < n <= 10) associated with the Virtual Input Device’s locator are 
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assigned an event code; the ith button is assigned the code BUT(i). Thus a 3-button mouse 
reports x and y and buttons 1-3. 

In the function class are the event codes associated with keyboard function keys that don’t gen¬ 
erate single ASCII charaters: 

#define KEY_LEFT(i) 

#define KEY_RIGHT(i) 

#define KEY_TOP(i) 

#define KEY.BOTTOMLEFT 
#define KEY_BOTTOMRIGHT 

The function keys in the Virtual Input Device define an idealized standard layout that groups 
keys by location: 16 left, 16 right, 16 top and 2 bottom. While the actual position on the key¬ 
board may be different, it is convenient to provide some grouping for the large number of func¬ 
tion keys. The mapping to physical keys on various keyboards is defined in 
f uarjinclude/sundevjkbd.h and discussed in /;6d(5). 

5.1.2.3. Pseudo Events 

#define VKEY.FIRSTPSEUDO 
#define VKEY_LASTPSEUDO 

Event codes in the pseudo class are events that involve locator movement instead of physical 
button striking. The physical locator constantly provides an (x, y) coordinate position in pixels; 
this position is transformed by the Virtual Input Device to the coordinate system of the window 
receiving an event. In order to watch actual locator movement (or lack thereof), the client must 
be enabled for the events with codes. 

#define LOC.MOVE 

#define LOC_MOVEWHILEBUTDOWN 

#define LOC.STILL 

A LOC_MOVE is reported only when the locator actually moves. Since fast motions may yield 
non-adjacent locations in consecutive events, the locator tracking mechanism reports the current 
position at a set sampling rate currently 40 times per second. 

LOC_MOVEWHILEBUTDOWN is like LOC_MOVE but happens only when a button on the 
locator is down. 

A single LOC_STILL event is reported when the locator has been still for a moment, currently 
1/5 of a second. 

Clients can be notified when the locator has entered or exited a window via the event codes: 

#define LOC_WINENTER 
#define LOC_WINEXIT 


5.1.3. Event Flags 

Only one event flag is currently defined: 

#define IE_NEGEVENT 

indicates the event was “negative.” Positive events include depression of any button or key. 
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including buttons on the locator, motion of the locator device while it is available to this client, 
and entry of the cursor into a window. The only currently defined negative event is the release 
of a depressed button. Stopping of the locator and locator exit from the window are positive 
events, distinct from locator motion and window entry. This asymmetry allows a client to be 
informed of these events without the performance penalty associated with receiving all negative 
events and then discarding all but these two. 

Two macros are defined to inquire about the state of this flag: 

#define win_inputnegevent(ie) 

#define win_inputposevent(ie) 
struct inputevent *ie; 

These are TRUE or FALSE if the IE_NEGEVENT bit is 1 or 0 respectively in the input event 
pointed to by it. 


5.1.4. Shift Codes 

Ie_»h{ftma»k contains a set of bit flags which indicate an interesting state when an input event 
occurs. The most obvious example is the state of the Shift or Control keys when some other 
key is pressed. Eventually, clients will be able to declare any Virtual Input switch as an 
“interesting” shift switch. For now, only the following bits are reported: 

#define CAPSMASK 0x0001 

#define SHIFTMASK OxOOOE 

#define CTRLMASK 0x0030 

#define UPMASK 0x0080 

These are defined in /u$rf include/tundev/kbd.k, and described in kbd{5). 

5.2. Reading Input Events 

A library routine exists for reading the next input event for a window: 

Int input_rcadevent(fd, ie) 

Int fd; 

struct inputevent *ie; 

This fills in the indicated struct, and returns 0 if all went well. In case of error, it sets the glo¬ 
bal variable errno, and returns -1; the client should check for this case. 

A window can be set to do blocking or non-blocking reads via a standard fcntl system call, as 
described in fetnl(2) and /cn(/(5). A window is defaulted to blocking reads. The blocking status 
of a window can be determined by the fcntl system call. 

The recommended normal style for handling input uses blocking I/O and the «c/ect(2) system 
call to await both input events and signals such as SIGWINCH. This allows a signal handler to 
merely set a flag, and leave substantial processing to be performed synchronously when the 
telect returns. The to al_»elect mechanism described in chapter 7 illustrates this approach. 
Using blocking I/O and rcod(2) without a prior eelect forces the client to process SIGWINCHes 
entirely in the asynchronous interrupt handler. This necessitates extra care to avoid race condi¬ 
tions and other asynchronous errors. 
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Non>blocking I/O may be useful in a few circumstances. For example, when tracking the mouse 
with an image which requires significant computation, it may be desirable to ignore all but the 
last in a queued sequence of motion events. This is done by reading the events, but not process* 
ing them until a non>motion event is found, or until all events are read. Then the most recent 
mouse location is displayed, but not all the points covered since the last display. When all 
events have been read and the window is doing non-blocking I/O, inputjreadevent returns -1 
and the global variable errno is set to EWOULDBLOCK. 


5.3. Input Serialization and Distribution 

With the exception of some of the pseudo event codes, the Virtual Input Device described in 
preceding sections is not logically tied to the Sun window system; the scheme could be used by 
any system desiring that form of unification. This section is more specific to the window sys¬ 
tem, since it discusses how events are selected and distributed among the various windows 
which might use them. 

Each user input event is formatted into an inputevent, which is then assigned to some recipient. 
There are three ways a process gets to receive an input event: 

• Most commonly, it reads the window which lies under the cursor, and that window has an 
input mask which matches the event. Input masks are described in Input Masks. If several 
windows arc layered under the cursor, the event is tested first against the input mask of the 
topmost window. 

• If the event does not match the input mask of one window, other windows will be given a 
chance at it, as described below. 

• Much less frequently, a window will be made the recipient of all input events; this is dis¬ 
cussed under win_grahio, in section 5.3.2 below. 

Each window designates another window to be offered events which the first will not accept. By 
default this is the window’s parent; another backstop may be designated in a call to 
win__sctinputmask, described in the next section. If an event is offered unsuccessfully to the root 
window, it is discarded. Windows which are not in the chain of designated recipients never 
have a chance to accept the event. 

If a recipient is found, the locator coordinates are adjusted to the coordinate system of the reci¬ 
pient, and the event is appended to the recipient’s input stream. Thus, every window sees a 
single stream of input events, in the order in which the events happened (and time-stamped, so 
that the intervals between events can also be computed), and including only the events that 
window has declared to be of interest. 


5.3.1. Input Masks 

The input masks facilitate two things: 

• Events can be accepted or rejected by classes; for instance, a process may want only ASCII 
characters. 

• The times when events are accepted can be controlled, minimizing the processing required 
to accept and ignore uninteresting events. For instance, a process may track the mouse 
only when it is inside one of its windows, or when one of the mouse buttons is down. 

Clients specify which input events they are prepared to process by setting the Input mask for 

each window being rezui. 
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struct inputmask { 
short im_flags; 

char imjinputcode(IM_CODEARRAYSIZE]; 

short imjshifts; 

short im_shiftcodes[IM_SHIFTARRAYSIZE]; 

}; 

#define IM_CODEARRAYSIZE (VKEY_CODE/((8izeof char)*BITSPERBYTE)) 
#define IM^SHIFTARRAYSIZE ((sizeof 8hort)*BITSPERBYTE) 

Im_flag» specifies the handling of related groups of input events: 

#define IM_UNENCODED 

indicates that no translation of physical device events should be performed. The Virtual Input 
Device should not intervene between the window and the user input. In this case, the most 
significant byte of ie_coie in an input event is the id number of the device that generated the 
event, and the least significant byte contains the physical keystation number of the keystation 
that the user struck. The current device ids are those assigned to the supported keyboards and 
the id assigned to the mouse 

#define MOUSE_DEVID 127 

For unencoded mouse input, the least significant byte of'the event code is identical to the least 
significant byte of the corresponding encoded input event. Note that unencoded pseudo events 
are associated with the physical locator; that is, a button*push on a tablet puck will generate a 
different code from a corresponding button*push on a mouse. 

#define IM^SCII 

indicates that the Virtual Input Device translation should occur. 

#defineIM^NSI " 

indicates that the process wants keystrokes to be interpreted as ANSI characters and escape 
sequences: normal ASCII characters are represented by their ASCII code in ie_code, described in 
Uniform Input Evento. Function keys with a standard interpretation, such as the cursor control 
keys, are represented by a sequence of input events, whose ie_eodea are ASCII characters starting 
with ESC. See k6(f(5) for further details. 

#define IM_POSASCII 

indicates that the client only wants to be notified of positive events for ASCII class events, even 
though IM_NEGEVENT is enabled. 

Note: The current implementation automatically enables both IM_ANSI and IM_POSASCII 
when IM_ASCII is specified. 

Requesting a particular function event in addition turns off any ANSI escape-coding for that 
function event. 

#4efine IM.META 

indicates that META-translation should occur. This means ASCII events that occur while the 
META key is depressed are reported with codes in the META range. Note that IM_META does 
not make sense unless IM_ASCII is enabled. 
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#define IM.NEGEVENT 

indicates that the client wants to be notified of negative events as well as positive ones. See 
Event Flags for a discussion of positive and negative events. 

Imjlnputcode is an array of bit flags indexed by biased event codes. A 1 in the ith position of 
the bit array indicates that the event with code VKEY_FIRST+» should be reported. This 
filter applies in both IM_UNENCODED and IM_ASCII modes. 

There are two routines which are of interest here. 

win_setinputmask(windowfd, acceptmask, fiushmask, designee) 
int windowfd; 

struct inputmask ’•'acceptmask, *flushmask; 

int designee; 

sets the input mask for the window identified by windowfd. Acceptmask addresses the new 
mask — events it passes will be reported to this window after the call to winjsetinputmask. 

Flushmask specifies a set of events which should be flushed from this window’s input queue. 
These are events which were accepted by the previous mask, and have already been generated, 
but not read, by this window. This is a dangerous facility; type-ahead and mouse-ahead will 
often be lost if it is used. The most obvious application is for confirmations, but these can be 
better implemented by requiring the confirmation within a short time-out. 

Note: If Jluskmask is non-NULL, the current implementation flushes all events from the queue, 
not just those specified in flushmask. 

Designee is the window number, which specifies the next potential recipient for events rejected 
by this window. If it is set to WIN__NULLLINK (defined in 
jusrf include!sunwindowjwin_struct.ii), i* interpreted as designating the window’s parent. 

Note: Changing masks in response to some input should be done with caution. There will be a 
lapse of time between the event which persuades the client it wants a new mask and the time 
the system interprets the resulting call to win_jsetinputmask. Events which occur in this interval 
will be passed or discarded according to the old input mask. Thus, it is probably not appropri¬ 
ate to wait for a button down before requesting the corresponding button-up; the button-up 
may arrive and be discarded before the mask is changed. It’s less dangerous to wait until a but¬ 
ton goes down to start tracking the mouse, since the client will be caught up as soon as the first 
motion event arrives. But even here, it’s better to ask for the LOC_MOVEWHILEBUTDOWN 
event, and never change the mask. 

The input mask for a window is read with 

win_getinputmask(windowfd, im, designee) 
int windowfd; 

struct inputmask *im; 

int *deslgnee; 

The input mask for the window identified by windowfd is copied into the buffer addressed by 
im. The number of the window that is the next possible recipient of input is copied into the int 
addressed by designee. 

We return to winjinput.h for these routines useful for manipulating input masks. The first 
three are macros: 
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^define win_8etinputcodebit(im,code) 
struct inputmask *im; 

char code; 

seta the bit indexed by code in the input mask addressed by tm to 1. 

# define w in_un5etinp utcodebit(im ,code) 
struct inputmask ’"im; 

char code; 

resets the bit to zero. The routine: 

$^define ■win_getinputcodebit(im, code) 
struct inputmask ■^im; 

char code; 

returns non-zero if the bit indexed by code in the input mask addressed by im is set. 

input_imnuU(mask) 

struct inputmask ■i^mask; 

is a procedure which initializes an input mask to all zeros. It is critical to initialize the input 

mask explicitly when the mask is defined as a local procedure variable. 


© 


5.3.2. Seizing All Inputs 

Normally, input events are directed to the window which underlies the cursor at the time the 
event occurs. Two procedures modify that behavior. A window may temporarily seize all 
inputs by calling; 

win_grabio(windowfd) 
int windowfd; 

The caller’s input mask still applies, but it receives input events from the whole screen; no win¬ 
dow other than the one identified by windowfd will be offered an input event or allowed to write 
on the screen after this call. 

wlnjreleaseio(windowfd) 
int windowfd; 

undoes the effect of a win_grabio, restoring the previous state. 

5.4. Event Codes Defined 

In the following table are collected together all of the special event code names discussed above. 
These names define values which appear in the ie_code field of an inputevent. As the system 
evolves, the particular value bound to a name is likely to change, thus event codes should be 
compared to the symbolic names below, not to the current values of those names. 


© 
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#define ASCn_FIRST (0) 

#define ASCII_LAST (127) 

#define META_FIRST (128) 

#define META.LAST (255) 

#define VKEY_CODES (128) 

#define VKEY_FIRST (32612) 


#define VKEY FIRSTPSEUDO 

#define LOC.MOVE 

#define LOC.STILL 

#define LOC.WINENTER 

#define LOC.WINEXIT 

#define LOC_MOVEWHILEBUTDOWN 

#define VKEY_LASTPSEUDO 


#define VKEY_FIRSTFUNC 

#define BUT_FIRST 
#define BUT(i) 

#define BUT.LAST 

#define KEY.LEFTFIRST 
#define KEY_LEFT(i) 

#define KEY.LEFTLAST 

#define KEY_RIGHTFIRST 
#define KEY_RIGHT(i) 

#define KEY.RIGHTLAST 

#define KEY.TOPFIRST 
#define KEY_TOP(i) 

#define KEY_TOPLAST 

#define KEY_BOTTOMLEFT 
#define KEY.BOTTOMRIGHT 

#define VKEY_LASTFUNC 


(VKEY.FIRST) 

(vkeyIfirstpseudo+ 0) 
(VKEY_FIRSTPSEUDO+ 1) 
(VKEY_FIRSTPSEUDO+ 2) 
(VKEY_FIRSTPSEUDO+ 3) 
(VKEY_FIRSTPSEUDO+ 4) 
(VKEY_FIRSTPSEUDO+ 15) 

(VKEY_LASTSHIFT+ 1) 

(VKEY.FIRSTFUNC) 
((BUT_FIRST)+ (i)-l) 
(BUT_FIRST+ 9) 

((BUT_LAST)+ 1) 
((KEY_LEFTFIRST)+ (i)-l) 
((KEY_LEFTFIRST)+ 15) 

((KEY_LEFTLAST)+ 1) 
((KEY_RIGHTFIRST)+ (i)-l) 
((KEY_RIGHTFIRST)+ 15) 

((KEY_RIGHTLAST)-f-1) 
((KEY_TOPFlRST)+ (i)-l) 
((KEY_TOPFIRST)+ 15) 

((KEY_TOPLAST)+ 1) 
((KEY_BOTTOMLEFT)+ 1) 

(VKEY_FIRSTFUNC+ 101) 


#define VKEY_LAST 


VKEY_FIRST+ VKEY_CODES-l 


There stre 3 synonyms for the common case of a 3-button mouse: 

#define MS_LEFT BUT(l) 

#define MS_MIDDLE BUT(2) 

#define MS_RIGHT BUT(3) 
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This chapter introduces the third and highest level of SunWindows, suntooU. It discusses how 
to write a tool: it covers creation and destruction of a tool and its subwindows, the strategy for 
dividing work among them, and the tise of routines provided to accomplish that work. 

At the euntooh level, the lower-level facilities are actually used to build user interfaces. This 
chapter also describes a model for building applications, a number of components that imple¬ 
ment commonly-needed portions of such applications, an executive and operating environment 
that supports that model, and some general-purpose utilities that can be used in this and simi¬ 
lar environments. 

We refer to an application program that is a client of this SunWindows level as a tool. Tool cov¬ 
ers the one or more processes that do the actual application work. This term also refers to the 
collection of typically several windows through which the tool interacts with the user. Simple 
tools might include a calculator, a bitmap editor, and a terminal emulator. Sun Microsystems 
provides a few ready-built tools, several of which are illustrated in Appendix B. Others may be 
developed to to suit particular needs. 

Common SunWindows tool components and their functions include: 

• An executive framework that supplies the usual "main loop” of a program, and which coor¬ 
dinates the activities of the various subwindows; 

• A standard tool window that frames the oubwindowt of the tool, identifying it with a name 
stripe at the top and borders around the subwindows. Each tool window can adjust its size 
and position, including layering, and subwindow boundary movement. 

• Several standard subwindows that can be instantiated in the tool; 

• A standard scheme for laying out those subwindows; and 

• A facility that provides a default tcon, which is a small form the tool takes to be unob¬ 
trusive but still identifiable. 

The suntooli program initializes and dversees the window environment. It provides for; 

• automatic startup of a specified collection of tools; 

• dynamic invocation of standard tools; 

• management of the window, called the root window, which underlies all tools and paints a 
simple solid color; 

• the user Interface for leaving the window system. 

Users desiring another interface to these functions can replace the suntooh program, while 
retaining specific tools. 
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The procedures that support the facilities described in this chapter and the following two are in 
the iuntool library, lusrfUbllibtuntooia), These procedures and their data structures ^ 
declared in a number of distinct header files, all of which can be included In 
f turl include/ iuntoolf tool_ha.h. 


6.1. Tools Design 

A typical tool is built as a tool window, and contained within that, a set of tubwindowt, which 
incorporate most of the user interface to the tool’s facilities. Each subwindow is a “window" in 
the sense described in Window Manipulation; the subwindows form a tree rooted at the tool win¬ 
dow, and the various tool windows are all children of the root window associated with the 
screen. 


6.1.1. Non-Pre-emptive Operation 

In general, tools should be designed to function in a non^pre-emptive style: they should wait 
without consuming resources until given something to do, perform the task expeditiously, and 
promptly return control to the user. If some task requires extensive processing, a separate pro¬ 
cess should be forked to run it without blocking the user interface. 

This non-pre-emptive style implies that the tool is built as a set of independent procedures, 
which are invoked as appropriate by a standardized control structure. The basic advice to 
client programs is, “Wait right there; we’ll let you know as soon as we have something for you 
to do." From a programming point of view, the main function that the tool mechanism provides 
is the provision of the control structure to implement this non-pre-emptive programming style. 
The tool window and its subwindows all have the same interface to this control mechanism. 


6.1.2. Division of Labor 

The tool window performs a few functions directly. These sffe the user interface functions, 
which are common to all tools. 

Subwindows are the workhorses of the tuntool environment, but most of the work they do is 
specific to their own tasks, and of little interest here. It is important to understand that a 
subwindow corresponds to a data type: there will be many instantiations of particular subwin¬ 
dows, quite possibly several in a single tool. 

Various types of subwindows are developed as separate packages that can be assembled at a 
high level. In addition to programmer convenience, this approach promotes a consistent user 
interface across applications. 

The remainder of this chapter divides a tool’s existence into two large areas: creation and des¬ 
truction, and tool-specific aspects of processing. 

6.2. Tool Creation 

All of the following processing must be done as a tool is started: 

• Parameters for this invocation of the tool must be passed to it. Every tool must be given 
the name of its parent window; other parameters that may be given to the tool include a 
position for it on the screen, whether it should be open or iconic, specification of data files, 
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such as fonts, to be used in this invocation, and initializations to be performed. 

• The tool should be given its own process and process group. In contrast to the usual pro¬ 
cedure in which a program is invoked under the shell, the parent process should generally 
be allowed to proceed before the child exits. 

• The tool window should be created with space allocated for it and its various options 
defined; similarly, its subwindows should be created and positioned in the tool window. 

• The UNIX signal system should be initialized to pass appropriate signals to the tool. 

® The tool’s window should be installed into the display structure. 

• Finally, the tool may start its normal processing. 

6.2.1. Paassmg Parameters to the Tool 

There are at least three ways parameters may be passed to a tool that is starting up; 

• Command-line arguments. 

• Relatively stable options may be stored in a file like a user profile. 

• Environment parameters may be used for well-established values. They have the valuable 
property that they can communicate information across several layers of processes, not all 
of which have to be involved. 

The first two parameters passing mechanisms need no special attention here, since they are used 
just as in non-window UNIX programs. However, SunWindows itself uses a few environment 
variables for tool startup. WINDOW_PARENT is set to a string that is the device name of a 
window’s parent; for a tool, this will usually be the name of the root window of the window sys¬ 
tem. WINDOWJNITIALDATA is set to the coordinates of two rectangles plus one flag. The 
rectangles are the regions for the window while open and closed, and the flag is a boolean that is 
non-zero if the tool should start out iconic. 

w ejsetparentw indow( w indevname) 
ch&r ®windevname; 

sets WINDOWJPARENT to windevname. 

int we_getparentwindow(windevname) 
char *windevname; 

gets the value of WINDOW_PARENT into wtndevname. The length of this string should be at 
least WIN_NAMESIZE characters long, a constant found in 
lutrlincludef$unwmdowfu)in_struet.h. A non-zero return value means that the 
WINDOW_PARENT parameter couldn’t be found. 

The process that is starting the tool should set WINDOWJNITIALDATA before it forks 
{wmgr_forktool does this; sec SuntooU: User Interface Utilities). After the fork, the newborn tool 
may interrogate these variables. The routines to do this are in the library 
/ US f/ Ubj libs unuiin dow.a. 

we_8etinitdata(rnormal, riconic, iflag) 
struct rect .*rnormal, *riconic; 

int iflag; 

sets the environment variable in the parent process, and 
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we getinitdata(rnormal. riconic, iflag) 
struct rect *rnormal, *riconic; 

int *iflag; 

reads those values in the child process. A non-zero return value means that the 
WINDOW_INITIALDATA parameter couldn't be found. 

A procedure is provided for unsetting WINDOW_IN!TlALDATA for tools that arc going to pro¬ 
vide windows for other processes to run in. This procedure prevents a wa]rward child process 
from being confused by the an incorrectly set variable: 

ll{te_clearinitdata() 


6.2.2. Forking the Tool 

A tool will normally have its own process. The creation of that process does not differ 
significantly from the normal paradigm for process creation. If it is to be started by a menu 
command or some other procedural interface, it is appropriate for the creating process to do the 
fork and return from the procedure call. When the child process dies, the parent process should 
catch the SIGCHLD signal and clean up. See the wat((2) system call. SIGCHLD indicates to a 
parent process that a child process has changed state. 


6.2.3. Creating the Tool Window 

The pair of procedures tool_create and tool_ereate»abwmdotD carry out the main work of creat¬ 
ing a tool with its subwindows. These take a series of parameters that define the object to be 
created, and return a pointer to an object that encapsulates the information about the tool or 
its subwindow. That pointer is then passed to a number of other routines that manipulate the 
object; the client is usually not concerned with the exact definition of the structure. 

These create routines include a large part of the processing described in the earlier parts of this 
manual, so that client programmers need not necessarily concern themselves much with the 
details of pixrecta and pizu'ins. 

A tool is created by a call to: 

struct tool *toot_create(name, flags, normalrect, icon) 
char '^name; 

short flags; 

struct rect *normalrect; 

struct icon *icon; 

#define TOOL_NAMESTRIPE 0x01 

#define TOOL_BOUNDARYMGR 0x02 

is the name of the tool. This is what will be displayed in the tool’s name stripe if 
TOOL_NAMESTRIPE is set in the flag’s argument. It also appears on the default 
icon. 

has the flags TOOL_NAMESTRIPE and/or TOOL_BOUNDARYMGR set as 
those properties are desired. (TOOL_BOUNDARYMGR enables boundaries that 
the user cam move between subwindows.) 


name 

flagt 
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Normalreet describes the initial position and size of the tool in its normal open state in the 
coordinate system of the tool’s parent, which is typically the window for the 
screen. 

teon is a pointer to an icon struct, if the client wants a special icon. 

Normalreet and the icon may be defaulted by passing NULL for their arguments. The default 
icon is described, along with considerations for making custom icons, in Suntool: User Interface 
Utilitiee; the choice is strictly a matter of convenience vs. ambition. A tool’s starting position 
should almost always be left NULL; i^ could be the result of WE_GETINITDATA that is going 
into normalreet. 

Creating the tool does not cause it to appear on the screen; a separate step is used for that pur¬ 
pose after the full tool structure is constructed, as described in Tool Installation. Most tool pro¬ 
grammers can skim the following information to Subwindow Initialization and ignore the details 
of the tool and tooUw data structures. 


0.2*4. The Tool Struct 

The tool struct is defined in f usrIineludejsuntool/tooLh. It is: 
struct tool { 


short 

tl_flags; 

int 

tLwindowfd; 

char 

*tl_namc; 

struct 

icon *tlJcon; 

struct 

toolio tljo; 

struct 

toolsw *tljiw; 

struct 

pixwin ♦tl_pixwin; 

struct 

rect tl_yectcache; 


) 

Tl^ags holds state information. Currently, there are 6 defined flags: 


#define TOOL^NAMESTRIPE 0x01 

#define TOOL_POUNDARYMGR 0x02 

#define TOOLJCONIC 0x04 

#define TOOL_3IGCHLD 0x08 

#deflne TOOLJSIGWINCHPENDING 0x10 

#define TOOLJJONE 0x20 


Their actions are as follows; 

TOOL_NAMESTRIPE 

indicates that the tool is to be displayed with a black stripe holding its name at the 
top of its window. 

TOOL_BOUNDARYMGR 

enables the option that allows the user to move inter-subwindow boundaries. 
TOOLJCONIC 

indicates the cuirent state of the tool: 1 small (tcontc); 0 == normal {open). 
TOOL_SIGCHLD and 
TOOL_SIGWINCHPENDING 

mean that the tool has received the indicated signal and has not yet performed the 
processing to deal with it. 
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TOOL_DONE 

indicates the tool should exit the tool_»elect notification loop. 

The last three flags are used during tool_»clect processing described below and should be con¬ 
sidered private to the too! implementation. 

Tljmndowfd holds the file descriptor for a tool’s window. This is used for both input and 
output. It also identifies the window for manipulations on the window data¬ 
base, such as modifying its position or shape. Windowfds' uses are discussed in 
chapters 3 through 5. 

Tljnamt addresses the string that can be displayed in the tool’s namestripe and default 

icon. 

Tljrectcache holds a rectangle that indicates the size of the tool's window. Because the rec¬ 
tangle is in the tool’s coordinate system, the origin will always he (0, 0). This 
size information is cached so that the tool can tell when its size has changed by 
comparing the cached rcct with the current rect. 

Tl_ieon holds a pointer to the icon struct for this tool. 

Tljpixwi^ addresses the window’s pixwin, which is the structure through which the tool 

accesses the display. 

Tl_»w points to the first and oldest of the tool’s subwindows. The following section 

discusses these structs. 

The tool uses tljio to control notification of input and window change events to itself. To olio 
Structure details this structure type. During tool creation, the fields of this structure are set up 
with values to do default toot processing. 

6.2.5. Subwindow Creation 

After the tool is created, its subwindows are added to it. 

struct toolsw *tool_createsubwindow(tool, name, width, height) 
struct tool *tool; 

char *name; 

short width, height; 

#define TOOL.SWEXTENDTOEDQE -1 

makes a new subwindow, adds it to the list of subwindows for the indicated tool, and returns a 
pointer to the new toolsw struct. The width and height parameters are hints to the layout 
mechanism indicating what size the windows should be if there is enough room to accommodate 
them. There are no guarantees about maintaining subwindow size because changing window 
sizes can ruin any scheme. TOOLjSWEXTENDTOEDGE may be passed for width and/or 
height; it allows the subwindow to stretch with its parent in either or both directions. Subwin¬ 
dow Layout details the subwindow layout. The name is currently unused; it may eventually 
support the capability to refer to subwindows by name. 

The remaining subwindow initialization requires reference to the data structure: 
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struct toolsw { 


struct 

toolsw ♦ts_next; 

int 

t8_windowfd; 

char 

*ts_name; 

short 

ts_width; 

short 

ts_height; 

struct 

tooiio ts_io; 

int 

(*ts_destroyX); 

ca<!dr_t 

ts_data; 


}; 

The subwindows of a tool are chained on a list with t»_next in one subwindow pointing to the 
next in line, until the list is terminated with a null pointer. 

Like the tool window, each subwindow must have an associated open window device; 
tool_create»xtbwindow stores the file descriptor in td_windowfd. 

Tt_name, tt_mdth and tajivight are exactly as in the call to too{_ereatesubmndow. 

The tool uses tsjo to control notification of input and window change events to the subwindow. 
Upon subwindow creation, the tfjio structure has null values in it that need to be set. This is 
normally done by the efcutc routine for a standard subwindow type. Toolia Structure details 
this structure. 

Tt„deetroy gets called when the tool is being destroyed by tooljieetroy so that the subwindow 
may terminate cleanly. 

Tt_data provides 32 bits of uninterpreted data private to the subwindow implementation. Typi¬ 
cally, it will be a pointer to information for this instance of the subwindow. That is, all subwin¬ 
dows of the same type will share common interrupt handlers and layout characteristics. Win¬ 
dow contents and other information specific to one particular window will all be accessed 
through this pointer. This is discussed at more length in Requirements for Subtoindows in 
Chapter 7. 

6.2.6. Subwindow Layout 

By default, subwindows are laid out in their tool’s area in a simple left-to-right, top-to-bottom 
fashion, in the order they are created. A subwindow is placed as high as it can be, and in that 
space, as far to the left as it can be. 

Subwindows that should be arranged in a more controlled fashion may be rearranged after they 
have all been created, using the rectangle manipulation facilities described in Window Geometry. 
Three functions return numbers useful to tools doing their own subwindow layout explicitly: 

short tooljstripeheight(tool) 
struct tool 't'tool; 

returns the height in pixels of the tool’s name stripe. 

short tool_borderwidth(tool) 
struct tool *tool; 

returns the width in pixels of the tool’s outside border. 
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short tool_subwindowspacing(tool) 
struct tool *tool; 

returns the number of pixels that should be left as a margin between subwindows of a tool, 
currently the same as the outside border of the tool. 


6.2.7. Subwindow Initialization 

By the time toot_create8ubwtndow has returned, the subwindow is already inserted in the tree 
growing out of the tool window; however, the subwindow will not perform any interesting func¬ 
tion until t$_io and t»_data have been initialized. Normally, toot_ereatetubwmdow is not directly 
called. Instead, the tool subwindow creation procedure for a subwindow type is called. The 
subwindow specific routine will call tool_createtubmndow and then initialize tsjlit and t8_data. 


6.2.8. Tool Installation 

Once the tool is created and its subwindows have been created and installed, the software inter¬ 
rupt system should be turned on via a call to ttgnal as described in Window Change 
Notificationt. At least SIGWINCH should be caught; if there are inferior processes in any of the 
subwindows, SIGCHLD should be added with any others as appropriate. Finally, the tool is 
installed into the display window tree by a call to: 

tool_install(tool) 

struct tool ■•'tool; 

At this point, the tool is operating; in fact, it will probably shortly receive a SIGWINCH asyn¬ 
chronously to paint its window(8) for the first time. 


6.2.9. Tool Destruction 

Explicitly destroying a tool as it reaches the end of its processing allows the system to reclaim 
resources and remove the windows gracefully. The procedure to invoke this cleanup is: 

tool_destroy(tool) 

struct tool '•'tool; 

Tool_de»troy will destroy every subwindow of the indicated tool as part of its processing, so the 
subwindows need not be destroyed explicitly. Each subwindow’s t»_destroy procedure gets 
called, so they can clean up gracefully. The pointer passed to tool_de»troy must never be 
dereferenced after that call, since it is no longer valid. 

A single subwindow can be destroyed by an explicit call to: 

tool_destroysubwindow(tool, subwindow) 
struct tool «tool; 

struct toolsw '‘subwindow; 

A tool may use this procedure to change its subwindows, while continuing to run. 
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6.3« Tool Processing 

The main loop of a normal tool is encapsulated inside a call to: 

tool_select(tooI, waitprocessesdie) 
struct tool ’■'tool; 

int waitprocessesdie; 

This procedure is the notification distributer used for event-driven program control flow. When 
some input event, timeout or signal interrupt is detected inside toot_select, a call to a 
notification handier is made, passing in the toolio structures of the tool and its subwindows. 
When the handler returns, too!_»eleet awaits another event. The waitprocessesdie argument is 
discussed below in Child Process Management. 


6.3.1. Toolio Structure 

The toolio data structure in each toolsw structure holds what is needed for a subwindow to wait 
for something to happen in the tool_8elect call. The toot structure uses the toolio data structure 
within itself to wait for input too. It is defined in f usr/include/suntool/tool.h. 

struct toolio { 


int 

tiojnputmask. 

int 

tio_outputmask. 

int 

tio_exceptmask; 

struct 

timeval ♦tio_tinier; 

int 

('»tio_handle8igwinch) (); 

int 

(♦tiojselectcd) (); 


}; 

Tio_inputmask, tio_outputmask, tio_exceptmask and tiojtimer fields are analogous to the last 
four arguments to the select system call. Tio_inputmask has the bit "!<</'’ set for each file 
descriptor / on which a window wants to wait for input. Similarly, tio_outputmask and 
tio_ezceptmask indicate an interest in / being ready for writing and having an exceptional condi¬ 
tion pending, respectively. There are currently no “exceptional conditions" implemented; this 
field provides compatibility with the select system call. 

If tio_fimer is a non-sero pointer, it specifies a maximum interval to wait for one of the file 
descriptors in the masks to require attention. If tiojtimer is a zero pointer, an infinite timeout 
is assumed. To effect a poll, the tiojtimer argument should be non_zero, pointing to a timeval 
structure with all zero fields. 

Toolio also contains pointers to the procedures that are called when the tool has received some 
notification. Tiojtandlesigmneh addresses the procedure that responds to the SIGWINCH sig¬ 
nal. This procedure handles repaint requests and window size changes. The general form for 
such a procedure is: 

sigw inc h_handler(data) 
caddr_t data; 

Such procedures take a single argument data whose type is context-dependent. For a tool this 
data is a pointer to the toot structure. For a subwindow this data is the ts_data value in the 
toolsw structure. 

Tio_seteeted addresses the procedure which responds to notifications from the select system call. 
The procedure’s calling sequence is: 
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io_handler(data, ibits, obits, ebits, timer) 


caddr_t 

data; 

int 

’‘ibits. 

int 

’‘obits. 

int 

’‘ebits. 

struct 

timeval ’‘’‘timer; 


In such procedures, the data argument is like that of the SIGWINCH handlers described above. 
The three integer pointers indicate which file descriptors are ready for reads writes 

or exception-handling (*ebiti). If timer is NULL, this window was not waiting on any 
timeout. If *t%mer points to a valid struct timeval then this window is waiting for a timeout. If 
both the (*timer)->tv_»ec and (*ttmer)->tv_u$ec are zero, the timeout has just happened for 
this window and should be serviced. The data in the file descriptor masks is not defined if a 
timeout has occurred. 

Before returning from a procedure of this type, the masks and timer must be reset by storing 
through the pointers passed in the arguments; the values should be consistent with the discus¬ 
sion of the masks and timer pointer above. You may not want to reset the timer if you are 
using it as a countdown timer, and it still has time remaining on it. 


6.3.2. File Descriptor and Timeout Notifications 

Tool_eelect generates three composite masks from each of the three toolio structures in the tool. 
The input mask is special in that if all the masks in a particular toolio structure are zero, an 
entry in the composite input mask is made for the associated window anyway. Toot_aelect also 
determines the shortest timeout that any of the windows is waiting on. The composite masks 
and shortest timeout are passed to the select system call. 

When the select system call returns normally, windows that have a match between their masks 
and the mask of ready file descriptors that have timed out, are notified via their tiojselected 
procedure. The <io_«e/cc#ed procedures are called with the complete ready masks, not just the 
intersection of its own masks and the ready masks. However, a tiojseleeted procedure is called 
with its own window’s timer value. 

Each window that has been selected as a result of the select system call is notified. The order of 
notification is not defined. Problems will arise if there are multiple non-cooperating windows 
waiting on the same device. 

It should be noted that timers in this implementation are only approximate. When the select 
system call returns and a timeout hasn’t occurred, the select is assumed to have been instan¬ 
taneous. Also, the time taken up with handling notifications is not deducted from the timers. 

6.3.3. Window Change Notifications 

Clients of the tool interface must catch the SIGWINCH signal. A signal catcher can be set up 
via the signat(S) library call. That catcher is then responsible for notifying the tool package 
that the signal has arrived. This is done by calling; 

tool_sigwinch(tool) 

struct tool ’•'tool; 

This procedure simply sets the TOOL_SIGWINCHPENDING flag in tool. The receipt of any 
signal has the side effect of causing the select system call in tool_select to return abnormally. 
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The TOOL_SIGWINCHPENDING flag is noticed and the tool’s tio_handleeigwinch procedure is 
called. The default tio_handle$tgmneh procedure does some processing, which may include 
changing the subwindow layout, and eventually calls all its subwindows’ tio_handlesigwinch pro¬ 
cedures. 


6.3.4. Child Process Maintenance 

Tool_»elect also gathers up dead children processes of the tool. The waitprocessesdie argument 
to tool_tdeet is provided for tools which have separate processes behind some of their subwin¬ 
dows. Such tools must explicitly catch SIGCHLD, the signal that indicates to a parent process 
that a child process has changed state. Then the signal handler, parallel to a SIGWINCH 
catcher and tool_$igwineh, should call: 

tool_8igchld(tool) 

struct tool *tool; 

This call causes tool_teleet to try to gather up a dead child process via a waits system call (see 
wat((2)). When as many child processes have been gathered up as indicated by the waitpro- 
ceneidie argument to tool_jelect, tooljtelect returns. 

6.3.5. Changing the TooPs Image 

During processing, a call to: 

tool_display(tool) 

struct tool '•■tool; 

redisplays the entire tool. This is useful if some change has been made to the image of the tool 
itself, for instance if its name or its icon’s image have been changed. Normal repaints in 
response to site changes or damage should not use this procedure. They will be taken care of 
by SIGWINCH events and their handlers. 

6.3.6. Terminating Tool Processing 

During the time that tool_sclect is acting as the main loop of the program, a call to: 

tool_done(tool) 

struct tool '•'tool; 

causes the flag TOOL_DONE to be set in tool. Tool_»eleet notices this flag, and then returns 
gracefully. 

6.3.7. Replacing Toolio Operations 

Since the toolio structure contains procedure pointers in variables, it is possible to customize the 
behavior of a window by replacing the default values. 

Icons that respond to user inputs or that update their image in response to timer or other 
events, may be implemented by replacing the tool’s tool_s€lected procedure. A different subwin¬ 
dow layout scheme may be implemented in a replacement procedure for tio^Jiandleaigwinch. 
Note that these modifications do not require changes to existing libraries; the address of the 
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substitute routine is simply stored in the appropriate slot at run-time. However, the substitute 
routine must either do all of the processing handled by the original library routine, or the sub¬ 
stitute routine should do its special processing and then call the original library routine. 
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Chapter 7 

Suntool: Subwindow Packages 


This chapter describes tuiwtndow packages, the building blocks for constructing a tool. It 
presents a guide for building new subwindow packages of general utility and describes the avail¬ 
able standard subwindow packages for use with suntooU. Refer to Suntool: Tools and Subwin¬ 
dows for a description of the overall structure of tools and the general notion of a subwindow. 

Subwindows, as presented here, are designed to be independent of the particular framework in 
which they are used. That is, a subwindow is a merger of window handling and application 
processing which should be valid in frameworks other than the tool structure and suntool 
environment described in the preceding chapter. The design avoids any dependence on those 
constructs. Thus, a subwindow pzu^kage can be used in another user interface system written on 
top of the sunwindow basic window system. However, subwindow packages all provide a utility 
for creating a subwindow in the tool context. 

© 

7.1. Minimum Stahdard Subwindow Interface 


This section describes the minimum programming interface one should define when writing a 
new subwindow package. A subwindow implementation should provide all the facilities 
described here. This section presents the arguments to the following standard procedures. Each 
subwindow package need only document any additional arguments passed to its createfinit pro¬ 
cedures. There is a set of naming conventions that provides additional consistency between 
subwindow package interfaces. 

For the purpose of example, we use foo as the prefix. Other prefixes used in existing subwin¬ 
dow packages include tty, gfz and msg. 

Each subwindow package has a structure definition that contains all the data required by a sin¬ 
gle instance of the subwindow. 

struct foosubwindow { 

int f8w_windowfd; 

struct pixwin *fsw jpixwin; 



The structure definition typically has a pixwin for screen access and a window handle for 
identification as part of this data. The information that the subwindow’s procedures need 
should be stored in this data structure; this may entail redundantly storing some data that is in 
the associated containing data structure, such as the toolsw struct. Having an object per 
subwindow allows multiple instantiations of a subwindow package in a single-user process. The 
following struct creates new instances of a foo subwindow: 
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struct foosubwindow ♦foos'w_init{'windowfd, 
int 'windowfd; 

Windowfd is to be a foo subwindow. The indicates that many subwindow packages will 

require additional set-up arguments. This routine typically opens a pizwin, sets its input mask 
as described in Input to Application Programs, and dynamically allocates and fills the 
subwindow’s data object. If the returned value is NULL then the operation failed. 

foosw_done(foosw) 

struct foosubwindow *foo8w; 

destroys subwindow instance data. Once this procedure is called, the fooaw pointer should no 
longer be referenced. 

foosw_handlesigw inch(foosw ) 

struct foosubwindow *foosw; 

This procedure handles repaint requests and must also detect and deal with changes in the win¬ 
dow size. It is called as an eventud result of some other procedure catching a SIGWINGH. 

foosw_8elected(foosw, ibits, obits, ebits, timer) 


struct 

foosubwindow *foosw; 

int 

♦ibits. 

int 

♦obits, 

int 

♦ebits. 

struct 

timeval **timer; 


handles event notifications. Subwindow packages that don’t accept input may not have a pro¬ 
cedure of this type. The semantics of this procedure are fully described in the preceding 
chapter in the section entitled Toolio Structure, 

struct toolsw *foosw_createtooIsubwindow(tool, name, width, height, ...) 
struct tool *tool; 

char *name; 

short width, height; 

creates a struct toolaw that is a foo subwindow. Fooaw_createtoolaubwindow is only applicable 
in the tool context. It is often the only call that an application program need make to set up a 
subwindow of a given type. Tool is the handle on the tool that has already been created. Name 
is the name that you want associated with the subwindow. Width and height are the dimensions 
of the subwindow as wanted by the tool^createaubwindow call. The “...” indicates that many 
subwindow packages will require additional arguments. These additional arguments should 
parallel those in /oo8U)_init. If the returned value is NULL then the operation failed. 
Fooau}_ereatetoolaubu)indow takes the window file descriptor it gets from tool_createaubwindow, 
passes it to fooaw_init, and stores the resulting pointer in the tool subwindow's ta_data slot. 
The addresses of fooawjhandleaigwinch and fooawjaelected stored in the appropriate slots of 
the toolio structure for the tool subwindow, and the address of fooaw^done is stored in the tool 
subwindow's ta_deatroy procedure slot. 

Of course, most subwindow packages define functions that perform application-specific process¬ 
ing; the ones described here are merely the permissible minimum. 
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7.2. Empty Sub window 

The empty subwindow package simply serves as a place holder. It does nothing but paint itself 
gray. It expects the window it is tending to be taken over by another process as described in 
Graphice Subvaindotv. When the other process is done with the empty subwindow package, the 
caretaker process resumes control. 

A private data definition that contains instance-specific data defined in 
ineludef suntoolf emptytw.h is: 

struct emptysubwindow { 
int em^windowfd; 

struct pixwin *em_pixwin; 

}; 

Emjwtndoivfd is the file descriptor of the window that is tended by the empty subwindow. 
Em_ptzwm is the structure for accessing the screen. 

struct toolsw *esw_createtoolsubwindow(tool, name, width, height) 
struct tool *tool; 

char '*name; 

short width, height; 

sets up an empty subwindow in a tool window. If the returned value is NULL then the opera¬ 
tion failed. Since e8Xv_createtooUubviftndow takes care of setting up the empty subwindow, the 
reader may not he interested in the remainder of this section. 

struct emptysubwindow *e3w_init(windowfd) 
int windowfd; 

creates a new instance of an empty subwindow. Windowfd is the window to be tended. If the 
returned value is NULL then the operation failed. 

e8w_handlesigwinch(e5w) 

struct emptysubwindow *e3W; 

handles SIGWINCH signals. If the process invoking this procedure is the current owner of 
c»w-> emjwindowfd, gray is painted in the window. If it is not the current owner, it checks to 
see if the current owner is still alive. If the current owner is dead, this process takes over the 
windows again and paints gray in the window. 

esw„done(e8w) 

struct emptysubwindow *e8w; 

destroys the subwindow*8 instance data. 

Processes that take over windows should follow guidelines discussed in Overlapped Windows: 
Imaging Facilities concerning the use of the win^etowner and win_setowner procedures. Prefer¬ 
ably, the graphics subwindow interface described below should be used for this activity. 



7.3. Graphics Subwindow 

The graphics subwindow package is for programs that need a single window in which to draw. 
Using this subwindow package insulates programmers of this type of program from much of the 
complexity of the window system. 
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Users of this interface have the additional benefit of being able invoke their programs from out¬ 
side the window system. Thus, you can write one program and have it run both inside and out¬ 
side the window system. This situation is actually an illusion. What really happens when run¬ 
ning outside the window system is that the window system is actually started up and that a sin¬ 
gle window is created in which the graphics subwindow package runs. 

The graphics subwindow can also manage a retained window for the programmer. The pro¬ 
grammer need not worry about the fact that he is in an overlapping window situation. A 
backup copy of the bits on the screen is maintained from which to service any repaint requests. 

The graphics sub window can be used in tool building like any of the other subwindow packages 
described in this chapter. However, the graphics subwindow also provides the ability for a pro¬ 
gram to run on top of an existing window by using the blanket window mechanism. 

The data definition for the instance-specific data defined in f utrfineludeltuntoolf gfxsw.h is: 
struct gfxsubwindow { 


int 

gfx„windowfd; 

int 

gfx_flags; 

int 

gfx_reps; 

struct 

pixwin *gfx_pixwin; 

struct 

rect gfxjrect; 

caddr_t 

gfx jtakeoverdata; 


}: 

#define GFX_RESTART 0x01 
#define GFX_DAMAGED 0x02 

Gfx_windowfd is the file descriptor of the window that is being accessed. Gfxjrtpa are the 
number of repetitions that continuously running (non-blocking) cyclic programs are to execute. 
Gfx_pixwin is the structure for accessing the screen. Gfxjrect is a cached copy of the window’s 
current self relative dimensions. Gfx_takeoverdata is data private to the graphics subwindow 
package. 

Gfx_flagt contains bits that the client program interprets. The GFXJ)AMAGED bit is set by 
the graphics subwindow package whenever a SIQWINCH has been received. In addition, the 
GFX_RESTART bit is set if the size of the window has changed or the window is not retained. 
The client program must examine these flags at the times described below. 

GFX_DAMAGED means that gfxsw_hanile»igwinck should be called. This flag should be exam¬ 
ined and acted upon before looking at GFX_RESTART. GFX_RESTART is often interpreted 
by a graphics program to mean that the image should be scaled to a new window size and that 
the image should be redrawn. Many continuous programs, graphics demos for instance, redraw 
from the beginning of a cycle. Other event-driven programs, graphics editors and status win¬ 
dows, for example, redraw from their underlying data descriptions. The GFX_RESTART bit 
needs to be reset to 0 by the client program before actually doing any redrawing. 


7.3.1. In a Tool Window 

A graphics subwindow in a tool context is only applicable for event-driven programs that use 
the tool_»elect mechanism. Any subwindow in a tool must use this notification mechanism so 
that all the windows are able to cooperate in the same process. 
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struct toolsw *gfx8w_createtoolsubwindow(tool, name, width, height, argv) 
struct tool *tool; 

char *name; 

short width, height; 

char **argv; 

sets up a graphics subwindow in a tool window. If argv is not zero, this array of character 
pointers is processed like a command line in a standard way to determine whether the window 
should be made retained “-r” and/or what value should be placed in gfxjrept “-n ####”. If 
the returned value is NULL then the operation failed. It is the responsibility of the client to set 
up tooUw->ts_io.tio_»elected if the client is to process input through the graphics subwindow. 

It is also the responsibility of the client to replace tooUto-'>ts_io.tio_handletigwinch with the 
client’s own routine to notify the client when something about his window changes. The client 
tiojiandleetguiinch will call ^zswjinterpretetigmneh described below. 

gfxsw_getrctained( gfx sw); 

struct gfxsubwindow *gfxsw; 

can be called to make a graphics subwindow retained if you choose not to do the standard com¬ 
mand line parsing provided by gfxaui_createtootaubwindow. It should be called immediately after 
the graphics subwindow is created. Destroying gfxaw-^gfxjprretained has the effect of making 
the window no longer retained. 

The procedure: 

gfx8wjnterpretesigwinch(gfxsw) 
struct gfxsubwindow *^xaw; 

is called from the client t%o_)iandleaigwineh to give the graphics subwindow package a chance to 
set the bits in gfxaw->gfx_flaga. The code in the client tiojkandleaigmnek then checks the flags 
and responds appropriately, perhaps by calling the gfxau>_handleaigivineh procedure that handles 
SIOWINOH signals: 

gfxswjiandlesigwihch(gfxsw) 

struct gfxsubwindow ‘»gfxsw; 

If the window is retained and the window has not changed size, this routine fixes up any part of 
the image that has been damaged. If the window is retained and the window has changed size, 
this routine frees the old retained pixrect and allocates one of the new size. If the window is 
not retained, the damaged list associated with the window is thrown away. The 
GFXJ)AMAGED flag is reset to zero in this routine. 

The procedure: 

gfxBW_done(gfx8w) 

struct gfxsubwindow «gfxsw; 

destroys the subwindow’s instance data. 


7.3.2. Overlaying an Existing Window 

The graphics subwindow provides the ability for a program to overlay an existing window. The 
empty subwindow described above is designed to be overlayed. 

The following procedure creates a new instance of a graphics subwindow in something other 
than the tool context: 
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struct gfxsubwindow ’♦gfxsw_init(windowfd, argv) 
int windowfd; 

char **argv; 

Windowfd should be zero; the assumption is that there is some indication in the environment as 
to which window should be overlayed. See we_getgfxwindow in Window Manipulation for more 
information. Argv is like argv in gfz»w_ereatetooUubwindow. In addition, arguments similar to 
the ones recognized by winjinitecreenfromargv are parsed. Thus, the program can be directed 
to run on a particular screen. If the returned value is NULL then the operation failed. 

When a screen is created from scratch, window system keyboard and mouse processing are not 
turned on. Gfxaw_tetinputmatk should be called instead of win_tetinputma»k when defining win¬ 
dow input (see below) in order to enable window system keyboard and mouse processing. This 
mechanism is used to allow programs that listen to the standard input to still run when started 
from outside the window system. 

Gfxjtakovcrdata in the returned gfxBubwindow data structure is not zero in this case. The struc¬ 
ture of the data that this pointer refers to is private to the implementation of the graphics 
subwindow. 

When a graphics sub^indow has overlayed another window, various signal catching routines are 
set up if the corresponding signals have no currently defined handler routines. 

The gfxiw_catcha{gwinch procedure is set up as the signal catcher of SIGWINCH: 

gfxsw_catchsigwinch() 

It, in turn, calls gfxaw_interpreteaigwinch. 

The gfxaw^eatchaigtatp procedure is set up as the signal catcher of SIGTSTP: 
gfxsw_catchsigt8tp() 

The graphics subwindow is removed from the display tree. The pixwin of the graphics subwin¬ 
dow is reset. SIGSTOP is sent to the the graphics subwindow’s own process. 

The gfxaw_eatehaigcont procedure is set up as the signal catcher of SIGCONT: 

gfxsw_catchsigcont() 

The graphics subwindow is inserted back into the display tree (presumably after 
gfxawjcatchaigtatp removed it). 

Continuous programs that never use a select mechanism should examine gfxaw-> gfx_Jlaga in 
their inain loop. Other programs that would like to use a select mechanism to wait for 
input/timeout should call; 

gfx8w_select(gfxsw, selected, ibits, obits, ebits, timer) 
struct gfxsubwindow *gfxsw; 

int (*selectedX), ibits, obits, ebits; 

struct timeval '^timer; 

as a substitute for the tool_aclcct. Selected is the routine that is called when some input or 
timeout is noticed. Its calling sequence is exactly like fooaw_aelected described at the beginning 
of this chapter. The only difference in the semantics of this routine and fooaw_8elected is that 
the gfxaw->gfx_flaga should be examined and acted upon in aelected. Selected may be called 
with no input pending so that you are able to see the flags when they change. 

pita, obita, ebita and timer, as well as gfxaw and aelected, can be thought of as initializing an 
internal toolio structure, which is then fed to the tool_aelect mechanism. 
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A substitute for the tool_done is: 

gfx sw_8electdone(gfxs'w) 

struct gfxsubwindow *gfxsw; 

Gfzsw_aelcctdone is called from within the selected procedure passed to gfxawjselect. 

Programs that are not using the mouse can call: 

gfxsw jaotu8ingmouse(gfx) 

struct gfxsubwindow *gfxsw; 

In certain cases, when the graphics subwindow is the only window on the display for instance, 
some efficiency measures can be taken. In particular, pixwin locking overhead can be reduced. 

gfxsw_setinputmask(gfx, imjset, im_flush, nextwindownumber, usems, usekbd) 
struct gfxsubwindow •I'gfxsw; 

int nextwindownumber; 

struct inputmask *im_set, *im_flush; 

int usems, usekbd; 

The calling sequence is essentially that of tv{n_tetinputmatk. Usems being non-zero means that 
mouse input is wanted and so the mouse is turned on for the screen (if currently off). Usekbd 
being non-zero means that keyboard input is wanted and so the keyboard is turned on for the 
screen (if currently off). See gfxstojinii (above) for a rationale for using Gfxswjsetinputmask 
instead of win_setinputmask, 

gfxsw_inputinterrupts(gfx, ie) 

struct gfxsubwindow *gfxsw; 

struct inputevent *ie; 

This utility looks at *ie. If *te is a character that (on a tty) normally does process control (inter¬ 
rupts the process, dumps core, stops the process, terminates the process), it does the similar 
action. This routine is meant to be a primitive substitute for tty process control while using the 
window input mechanism. 

7.4* Message Subwindow 

The message subwindow package displays simple ASCII strings. 

A private data definition that contains instance-specific data defined in 
f asrj inelxtdef suntoolf msgsxu.hW. 

struct msgsubwindow { 


int 

m8g_windowfd; 

char 

♦msgjjtring; 

struct 

pixfont *msg_font; 

struct 

rect msgjrectcache; 

struct 

pixwin ♦msg_pixwin; 


}; 

Msg_tetndowfd is the file descriptor of the window that is the message subwindow. Meg_string is 
the string being displayed using ms q f ont. Only printable characters and blanks are properly 
dealt with, not carriage returns, line feeds or tabs. The implementation uses msg_rectcacke to 
help determine if the size of the subwindow has changed. Msg pixwin is the structure that 
accesses the screen. 
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struct toolsw ♦msgs'w_createtool3ubwindow(tool, name, width, height, string, font) 


struct 

tool *tool; 

char 

*name; 

short 

width, height; 

char 

♦string; 

struct 

pixfont ♦font; 


is the call that sets up a message subwindow in a tool window. String is the string being 
displayed using font. If the returned value is NULL then the operation failed. Since 
magaw_createtoottubwindou> takes care of the set*up of the message subwindow, the reader may 
not be interested in the remainder of this section, except for magaw_aetatring. 

The following struct creates a new instance of a message subwindow: 

struct messagesubwindow *msgsw_init(windowfd, string, font) 
int windowfd; 

char * string; 

struct pixfont *font; 

Windowfd identifies the window to be used. String is the string being displayed using font. If 
the returned value is NULL then the operation failed. 

msgsw_setstring(msgsw, string) 

struct messagesubwindow *msgsw; 

char ^string; 

changes the existing magaw->mag_atring to atring and redisplays the window. 

msgsw_display(msgsw) 

struct messagesubwindow *msgsw; 

redisplays the window. 

msgsw_hand!e3igwinch(msgsw) 

struct messagesubwindow *msgsw; 

is called to handle SIGWINGH signals. It repairs the damage to the window if the window hasn’t 
changed size. If the window has changed size, the string is reformatted into the new size. 

m sgsw_done(m sgs w) 

struct messagesubwindow *msgsw; 

destroys the subwindow’s instance data. 

7.5. Option Subwindow 

An option subwindow (optionaw) presents a mouse-and'display-oriented user interface for setting 
parameters and invoking commands in an application program. It is the window system analog 
to entering command-line arguments and typing mnemonic commands to an application. 

An option subwindow contains a number of items of various types, each of which corresponds to 
one parameter. Existing item types include labels, booleans, enumerated choices, text parame¬ 
ters, and command buttons. Note: New item types and extensions to these existing types are 
contemplated. 

The program optiontool is provided as a simple example of the features discussed here. Familiar¬ 
ity with t|ie behavior of the program, and with its source file f uarf auntoolf arcf optiontool.e, are 
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helpful in reading this section. See the source code for the icontool in appendix B for a good 
example. 

The declarations for the optionsw package are found in the header file 
j wtJ inelxidejanntoolf optiontw.h. The file jutrjinclude!auntoolftool_hi.h can be included to 
provide the support header files for optiontw.h. Optionsw.k includes declarations of all the pub¬ 
lic procedures, as well as the following structures and their associated defined constants. The 
first provides a counted buffer for a text item’s value to be stored into: 

struct string_buf { 
ujnt limit; 

char ’"data; 

}; 

Data should point to an array of chars to be used as the buffer, and limit should be set to the 
site of that buffer. Use of this structure is described with optaw_ffetvalue in Explicit Client 
Reading and Writing or Item Valuet below. 

The second is used to identify the type as well as the value of a reference: 

struct typed_pair { 
uJnt type; 

caddr_t value; 

}; 

#dcfine IMjGRAPHIC 2 

#deflne IM.TEXT 3 

#define IM^TEXTVEC 4 


Type indicates what kind of object value points to. The current choices are indicated in the fol¬ 
lowing table: 

Table 7-1: Option Image Types 


Typo 

Value Should Be 

IM_GRAPHIC 

(struct pixrect*) 

IM_TEXT 

(char 

IM_TEXTVEC 

(char ’»*) 


In the TEXTVEC case, value points to the first element of an array of string pointers; the last 
element of the array should be a NULL pointer. These are currently used only in enumerated 
items described in Enumerated liema. 

7.5.1. Option Subwindow Standard Procedures 

This section describes the routines needed to conform to subwindow package norms. These rou¬ 
tines follow the general procedures provided in Minimum Standard Subtvindow Interface. 
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struct toolsw *optsw_createtoo!8ubwindow(tool, name, width, height) 
struct toot *tool; 

char *name; 

short width, height; 

creates an option subwindow within a tooL The handle tooUva-> tajdata is used for the optaw 
argument in calls to other procedures of the optionaw package to identify the affected window 
and its private data. If the returned value is NULL then the operation failed. The remainder 
of this section is of interest only to clients outside the tool system. 

In contexts other than a tool, optaw_init must be called explicitly. Similarly, provisions must be 
made for using the rest of the routines in this section. 

caddr_t optsw_init(fd) 
int fdj 

Optawjinit takes an fd that identifies the window to be used for the optionsw, and returns an 
opaque pointer, which identifies the created optionsw in future calls to the package. If the 
returned value is NULL then the operation failed. 

optsw_handleBigwinch(optsw) 
caddr_t optsw; 

is called to handle SIQWINCH signals. It repairs the damage to the window, and if the window 
has changed size, reformats the options as described below. 

optsw_selected(optsw, ibits, obits, ebits, timer) 
caddr_t optsw; 

int * ibits, * obits, debits; 

struct timevalue **timer; 

is called to handle user inputs. 

The cleanup routine for an optionaw is: 

optsw_done(opts w) 
caddr_t optsw; 

It frees all storage allocated for the subwindow and its items. Of course, the client should not 
attempt to use any pointer associated with the optionsw or its items after a call to this routine. 

7.5.2. Option Items 

Once an optionaw is created, it may be populated with option items. Each item is created by a 
call to the create routine for the desired type; this creates the item, adds it to the items for the 
optionaw, and returns an item handle (an opaque pointer which identifies it). 

In some general aspects, all items in the optionaw exhibit the same behavior. The left or middle 
mouse button indicates an item to be manipulated; the right button is left to the menu func¬ 
tion. Pressing one of the first two buttons gets the optionaw's attention, and releasing it actually 
completes a user-input event to which some item may respond. While the button is held down, 
the cursor may be slid around over the window, and each item it passes over will indicate its 
readiness to respond, typically by a reverse video display. Any such indication may be canceled 
simply by moving the cursor off the item before letting up on the button. 

E 2 K:h item is identified on the screen by a label, which may be either text or a picture provided 
by the client. This label is passed to the item creation routine in a typedjpair struct. In the 
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graphic case {type ==* IM_GRAPHIC), the pixrect passed pointer is used without further con¬ 
sideration by the optionsw implementation — the client may even change the image after the 
item is created. For text labels {type == IMJTEXT), several defaults provide a uniform style 
with minimal client effort. Text labels are displayed in a bold-face version of the current font. 
(The current font for the option subwindow starts as the window’s default font, and may be 
reset for each item, as described under opUwjietfont in Miacellany below.) The text of the label 
is modified to indicate the type of the item visually: 

Boolean items are surrounded by square brackets: ’‘[text]" 

Commands are surrounded by parentheses: “(text)” 

Enumerated items have a colon appended to their label, and braces surrounding the 
set of their values: “text: { choicel choice2 choices }” 

Text items have a co]on appended to their label: “text: <value>” 

Label items have their exact text presented in the bold face: “text”. 

The text of the label is copied by the optionsw implementation; it may not be modified by the 
client after the item is created. 

Clients which find these defaults too restrictive are free to generate their own labels (by using 
pfjtext into a memory pixrect, for example) and pass them in as type IM_GRAPHIC. 

7.5.2.I. Boolean Items 

The following procedure creates an item which maintains a boolean (TRUE or FALSE) value: 

caddr_t optsw_booI(optsw> label, init, notify) 
caddr_t optsw; 

struct typed_pair * label; 

int init; 

Int (*notifyX); 

Its label contains a pointer to a typed_pair as described above. The label is displayed in reverse 
video whenever the item is TRUE. The value of the item is initially set to init, and is toggled 
whenever the user selects the item. (It may also be set by a call to opt8U)_setvalue, as described 
below.) Whenever user action changes the value of the item, the procedure notify is called with 
the new value, as described in Client Notification Procedureo. This argument may be NULL to 
indicate that no notification is desired. 


7.5.2.2. Command items 


The following procedure creates an item that invokes the client procedure notify when selected 
by the user: 


caddr_t optsw_command(opt8w, label, notify) 
caddrjt optsw; 

struct typed_pair * label; 

int (*notifyX); 


The created item has no value. All three arguments are the same as their couterpzuts in 
optsw_bool. 
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7.5.2.3. Enumerated Items 

The following procedure creates an item in which exactly one of a set of choices is in effect at 
any time: 

caddr_t optsw_enum(opt3w, label, choices, flags, init, notify) 


caddrjt 

optsw; 

struct 

typed_pair *label; 

struct 

typedjpair ♦choices; 

int 

flags; 

int 

init; 

int 

(♦notify)(); 


The value is interpreted as a 0-based index into the choices for the selection. Optaw, label, and 
notify are as above. Choicea is a vector of images to be displayed for the choices; for now its 
type must be ITEM_VEC. This means that the data pointer for choicea addresses an array of 
string pointers, one for each possible choice plus a NULL indicating the end of the array. Init is 
the initial value of the item; it should be at most the size of the choicea array minus 2 (to avoid 
the null pointer which terminates the array). Flaga will eventually indicate layout options, but 
for now should be 0. 

7.5.2.4. Label Items 

The following procedure creates an item which does nothing but paint itself. This item type 
may be used to include labeling information in the option subwindow. 

caddr_t opt8W_labci(opt8w, label) 
caddr_t optsw; 

struct typedjair ♦label; 

Optaw and label are as above. 

7.5.2.5. Text Items 

The following procedures create an item which holds a text value; 

caddr_t optsw_text(optaw, label, default_value, flags, notify) 
caddrjt optsw; 

struct typed_pair * label; 

char *default_value; 

int flags; 

int (♦notifyX); 

#define OPT_TEXTMASKED 

Optaw, label, and notify are as above. Default_value is the initial value of the item. Flaga 
specify attributes of the created item; currently, only the maaked attribute is supported. If 
OPT_TEXTMASKED in flags is set, each character of the text item will be displayed as an asterisk. 
This feature is useful for text parameters which should not be displayed, such as passwords. 
The true value of the item is returned by optaw_getvalue described below. Notify is like the pro¬ 
cedures of the other item-creation routines. It is called whenever the value of the text item is 
changed, except by a call to optaw_aetvalue. Its arguments are handles for the optionsw and the 
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item. Optaw_jetvalue should be used to actually retrieve the new value. This pzu-ameter to 
cptew_texi may be I>nJLL to indicate ’no notification.’ 

There may be multiple text items in an option subwindow. At any time, one of them “has the 
caret,’’ Any keystrokes directed to the option subwindow will be directed to this item. The 
item that has the caret is indicated by a box around its label. Initially, this is the first text 
item created in the option subwindow. The user may set the caret in another item by clicking 
either the left or middle mouse button while the cursor is pointing at the new item’s label. 

The caret may also be determined and reset programmatically by calls to the following pro¬ 
cedures; 

caddr_t optsw_getcaret(opt8w) 
caddr_t optswj 

returns an item handle for the item that currently has the caret. 

caddr_t optsw_setcaret(optsw, ip) 
caddr_t optsw; 
caddr_t ip; 

sets the caret on the item indicated by ip, and returns ip if successful. Otherwise, it returns 
NULL. Ip should be a handle on a text item. 

Only displayable characters will be accepted in the item (ASon codes 040-0176 inclusive). The 
user’s erase (character delete) and kill (line delete) characters are available for editing existing 
text. The first will delete the last character of the text; the latter will delete the whole string. 
Other characters will be discarded. 

Text items will expand to fit the remainder of their option subwindow’s width. This may be 
more polymorphism than clients desire. See the discussion under Item Layout and Relocation 
below. 

Note: This release of text items includes the following restrictions: 

• Values of text parameters are restricted to a single line of text, less than 1000 characters long. 
Characters which extend beyond the item's right edge will not be displayed, zdthougb they 
arc entered and edited the same as visible characters. 

• Text items may be edited only at their ends. The available operations are: add a character to 
the end, delete a character from the end, and delete the whole value. 

While significant extension to the functionality of text items is planned, the actual interface 
(the external procedure definitions and data structures) are designed to accommodate those 
extensions without change. 


7.5.3. Item Layout and Relocation — SIGWINCH Handling 

As each item is created, its width and height are determined and stored in the item’s private 
data. No left and top positions are assigned at this time. Later, whenever a signal is received 
which indicates that the size of the subwindow has changed (in particular, when the tool is first 
displayed, and the size grows from 0 to the initial window), a layout procedure determines posi¬ 
tions for all the items in the window. 

The default layout procedure starts in the upper-left comer of the subwindow and places items 
in successive positions to the right, and then in successive rows down the window. Item posi¬ 
tions are not normally fixed; items may be repositioned if the window is later laid out again 
with a different size. 


Revision D of 7 January 1984 


7-13 




Suntool: Subwindow Packages 


SunWindows Reference Manual 


If an item is encountered with either of its top or left edges fixed, that specification is accepted 
without further consideration — it is possible to lay one item down on top of a previously posi¬ 
tioned item, or to position it out of sight to the right or below the subwindow boundary. 

Positioning of subsequent items after an item with a fixed position may be affected in three 
ways: 

1. The top of the row in which the item appears may move down, but not up, for the rest of 
the items in the row. 

2. Subsequent items in the same row will not be positioned to the left of the item’s right edge. 

3. Items in subsequent rows will not be positioned above the bottom of the fixed item. 

If an item is encountered which does not have fixed width (currently, only a text item), an 
attempt will be made to expand the item to fill the remaining width in the option subwindow. 
This is done through a rather simple-minded negotiation between the general layout procedure 
and the flexible item. If both the position and width of the item are flexible, the result of this 
negotiation miay not be very satisfactory to observers. In most cases, the position, the width, or 
both should be fixed. 

At any time between an item’s creation and its destruction, the client may inquire or modify its 
current size and position. This is done via the following two procedures: 

opt8w_getplace(optsw, ip, place) 
caddr_t optsw; 

caddr_t ip; 

struct item_place * place; 

opt3W_seiplace( optsw, ip, place, reformat) 
caddr_t optsw; 

caddr_t ip; 

struct item_place * place; 

int reformat; 

Optsw is the handle returned by optswjinit. Ip is the pointer to an opt_item struct returned by 
the item’s create routine. Place is a pointer to a struct item_place described below. 

The optsw_setplace arguments are parallel to those of optsw_getplace. Place is a pointer to a 
struct item_place, which contains a rect and four boolean flags indicating that a value is to be 
fixed for that item. The reformat argument indicates that the window is to be laid out and 
displayed anew, taking the changed item into account. This should generally be done any time 
after the window has been opened, since the item is already displayed, but it may be postponed 
if a series of adjustments are to be made; in that case, it is appropriate to reformat only after 
the last item’s place is set. 

The following struct is also described in optionsw.k: 

struct item_placc { 
struct rect rect; 

struct { 

X : 1; 

y:i; 
w : 1; 
h : 1; 

} fixed; 

}; 
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Rcct indicates the current size and position of the item, and the four bit-fields fixed.x, fixed.y, 
fixed.w, and fixed.h are TRUE if the corresponding dimension may not be adjusted by the layout 
procedure. 

For convenience in laying out string items, two functions convert character columns and lines to 
the appropriate pixel coordinates: 

Int optsw_coltox(optsw, col) 
caddrjb optsw; 

int col; 

int opt8wJinetoy(optsw, line) 
caddr_t optsw; 

int line; 

The dimensions used in calculating these coordinates are the width of the character ‘a’ in the 
optionsw’s default font and the nominal height of that font, that is, the distance between base¬ 
lines of successive unleaded lines of text. Both columns and rows start at 0. 

7.5.4. Client Notification Procedures 

Most item types provide a mechanism for notifying clients that the value of an item has been 
changed by the user. The same general mechanism is used to specify the procedure to be 
invoked in response to selection of a command button. 

In each case, a pointer to a procedure is passed to the item-creation routine and stored with the 
item. This procedure pointer may be zero, in which case there is no client notification. When 
appropriate, this notification procedure is invoked by optiontw code with arguments to identify 
the affected subwindow and item, and the new value assigned to the item. The general form for 
these procedures is: 

notify(opt8w, item, value) 
caddr_t optsw; 
caddr_t item; 

int value; 

{ ... processing to respond to item's new value.) 

Procedures to be invoked in response to a command button-push have the same form, except 
there is no value parameter. Notification of changes to text items also omit the value parameter. 

Note that the notification procedure is provided by the client and invoked by the optionsw pack¬ 
age. 

7.5.5. Explicit Client Reading and Writing of Item Values 

Clients may read the current value of an item by calling the procedure: 

int optsw_getvalue(ip, dest) 
caddr_t ip; 

caddr_t dest; 

Ip is the item handle which identifies the item whose value is sought; de»t is the address of the 
destination in which the value is to be stored. For items with a numeric value, dett should actu¬ 
ally be a pointer to an int, the value will be stored in the indicated int, and returned as the 


Revision D of 7 January 1984 


7-15 





Suntool: Subwindow Packages 


SunWindows Reference Manual 


value of the function. Items which have no value (commands, labels) store and return -1. 

For text items, dest should be a pointer to a struct »tring_buf, whose limit is the length of the 
associated data array. Optsw_getvalue will store characters from the value of the indicated item 
into (*deat-> data), and return the number of characters stored. If there is room, a terminating 
NULL character will be written, and a later call to optaw_getvalue will store characters starting 
at the beginning of the item’s value. Otherwise, the data buffer will be filled and the returned 
count will be equal to deat->limit; the next call to optaw_getvalue for this item will resume stoiv 
ing characters with the first character not reported in the previous call. Multiple calls to 
optaw^getvalue may thus be used to retrieve a long value through a short buffer. Eventually, 
there will be room to store a null character, and the whole value will have been reported; the 
next call to optaw_getvalue for this item will restart at the beginning of the value. 

Clients may set the value of an item by calling: 

optsw_setvalue(optsw, ip, value) 
caddr_t optsw; 
caddr_t ip; 
caddr_t value; 

Optaw is the opaque handle on the option subwindow; it enables repainting of the modified item. 
Ip indicates the item to be modified. Value should be an appropriate value for the item, which is 
then cast to eaddr_t. That is, booleans and enumerateds should provide an int (or unsigned); 
text items should provide a (char *). For example, if optawjaetvalue is being used to change a 
boolean item, value could be: 

(caddr^t) FALSE 


7.5.6. Miscellany 

Clients may inquire and set the font that is being used for displaying item labels and values. 
Fonts for these objects are determined at the time the object is created; different items may use 
different fonts. Thus, the client may create an object, change the font, create more objects 
which will use the new font, and then change the font back (or to a third value) for succeeding 
items. 

struct pixfont *opt8w_getfont(opt8w) 
caddr_t optsw; 

returns the current font for the indicated optaw. 

opt8w_8etfont(opt8w, font) 
caddr_t optsw; 
struct pixfont *font; 

sets the optaw's font to be font. 

Given an item in an optionsw, the routine: 

optsw_nextitem(optsw, ip) 
caddr_t optsw; 
caddr„t ip; 

returns a handle for the next item in sequence. If ip is NULL, the first item in the window will 
be returned; if ip refers to the last item in the optionsw, NULL is returned. 
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The routine: 

optsw_yemo'veitem8(optsw, ip, count, reformat) 
caddr_t optaw; 

caddr.t ip; 

int count; 

int reformat: 

removes at most count items from opt$w, making them inaccessible to the user, but not destroy¬ 
ing them. They may be restored later by a call to optBW_restoreitems. The subwindow is 
redisplayed without them if reformat is TRUE. The number of items so removed is returned; 
this may be less than count if the items in the subwindow are exhausted before count has been 
removed. 

Starting at the item indicated by ip, the routine: 

opt8Wjre8toreitem8(opt8W, ip, count, reformat) 
caddr_t optsw; 

eaddrjt ip; 

int count; 

Int reformat: 

restores at most count items in oew and returns the number restored. This may be left than 
count if all extant for the optionsw are exhausted, or an item which is not currently removed is 
encountered, first. The subwindow is redisplayed with the restored items if reformat is TRUE. 

For assistance in implemeniihg applications which use option subwindows, two routines are pro¬ 
vided which print a formatted display of the optionsw and/or its items, to a stream of the 
client’s choice: 

optsw_dump8w(stream, optsw, verbose) 

FILE ^stream; 

caddrjb optsw; 

bool verbose; 

optswjdumpitem(file, ip) 

FILE ‘file; 

eaddrjt ♦ip; 

For each procedure, the client says where to write the dump with the ttream argument, and 
identifies the object to be dumped with the optaw or ip argument. If verbose is true, 
optaw_dumptw nin dump all the items of the optionsw. 


7.6. Terminal Emulator Subwindow 

This is the subwindow package that provides a Sun Terminal emulator. 

The private data definition that contains instance-specific data defined in 
/usr/include /auntooif ttyaw.h is: 

struct ttysubwindow { 

/• Private data*/ 

); 

Note: Only one TTY subwindow per process. 
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struct toolsw ♦ttysw_createtool3ubwindow(tool, name, width, height) 
struct tool *tool; 

char *name; 

short width, height; 

is the call that sets up a terminal emulator subwindow in a tool window. 
TtytwjereatetooUubwmdow takes care of setting up the terminal emulator subwindow except for 
the forking of the program. If the returned value is NULL then the operation failed. Thus, 
clients of this routine may want to ignore the remainder of this section except for the discussion 
of Uy»w_fork and perhaps ttyswjbccomeconsole. 

struct ttysubwindow ♦tty8w_init(windowfd) 
int windowfd; 

creates a new instance of a tty subwindow. Windowfd is the window that is to be used. If the 
returned value is NULL then the operation failed. 

tty sw_becomcconsole(tty8W) 

struct ttysubwindow *ttysw; 

sets up the terminal emulator to receive any output directed to the console. This should be 
called after calling tty$w_init. 

ttysw_saveparms(ttyfd) 
int ttyfd; 

should be called by the screen initialization program, e.g., «unfoo/s(l). This saves the charac¬ 
teristics of the terminal ttyfd in an environment variable. Terminal emulation processes forked 
from the screen initialization process will get their characteristics from this environment vari¬ 
able; terminal emulation processes started directly from shells get their characteristics from the 
standard error tty. Ttyiw_»aveparm$ is needed because a screen initialization program is often 
started from the console, whose characteristics can change due to console redirection. 

tty8w_handle8igwinch(ttysw) 

struct ttysubwindow *ttysw; 

is called to handle SIQWINCH signals. On a size change, the terminal emulator's display space is 
reformatted. Also, its process group is notified via SIQWINCH that the size available to it is 
different. Refer to TTY-Ba»ed Programs in TTY Subwindows. If there is display damage to be 
fixed up, the terminal emulator redisplays the image by using character information from its 
screen description. 

tty8w_selected(ttysw, ibits, obits, ebits, timer) 
struct ttysubwindow *ttysw; 

Int *ibits, *obits, *ebits; 

struct timeval **timer; 

reads input and writes output for the terminal emulator. * Ibits, *obits and *timcr are modified 
by ttysw_8elected. See the general discussion of tio_seleeted type procedures in Minimum Stan¬ 
dard Subwindow Interface. 

int tty3w_fork(ttysw, argv, inputmask, outputmask, exceptmask) 
struct ttysubwindow *tty8w; 

char **argv; 

int *inputmask, ^outputmask, *exceptmask; 
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forks the program indicated by *argv. The identifier of the forked process is returned. If the 
returned value is -1 then the operation failed and the global variable errno contains the error 
code. There are the following possibilities: 

• If ’^argv is NULL, the user SHELL environment value is used. If this environment parameter is 
not available, / binfth is used. 

• If *aTgv b “-c”, this flag and argvflj are passed to a shell as arguments. The shell then runs 
argvflj. The argument list for this case becomes ahdll-cf argv[l}j0. 

• If Hrgv is not NULL, the program named by argvlOj is run with the arguments given in the 
rest of argv. The argument list should be NULL terminated. 

The arguments *mputma»k, *ouputmask, *ezceptmask are dereferenced by ttysw_fork and set to 
the values that the terminal eumlator subwindow manager wants to wait on in a subsequent 
select eaU. 

tty8W„done{tty8w) 

struct ttysubwindow *ttysw; 

destroys the subwindow’s instance data. 


7.6.1. TTY-Baaed Programs in TTY Subwindows 

TTY'based programs, such as csh, sk, and vt, which use the termcap to determine the size of 
their screen, need not know about windows to run reasonably under the terminal emulator. 
The termcap library will return the current number of lines and columns of the terminal emula¬ 
tor. However, if the user changes his window’s size while one of these programs is running, the 
terminal emulator and the program may disagree about what the terminal size is. 

In the case of a size change, the terminal emulator sends a SIGWINCH signal to its process group. 
If a child process doesn't catch the signal, no harm is done because the default action for 
SIGWINCH is that the signal be ignored. A child process can catch the signal, and then requery 
the termcap library for the correct terminal size. Unfortunately, no TTY-based programs do 
this now. 

The terminal emulator and the Urmcap library communicate size information through ioctl sys¬ 
tem calls on the pseudo-tty shared by both. The terminal emulator makes a TIOCSSIZE ioctl 
call to set the size of the pseudo-tty. The termcap library or some other TTY-based program 
makes a TIOCGSIZE ioctl call to get the size of the pseudo-tty. These constants and the data 
that they pass in the ioctl call are further defined in /usrf includef sysf ioctl.h. 

int we_getmywindow(windowname) 
char *windowname; 

can be called by programs running under a window system pseudo-tty to find out the terminal 
emulator’s window name. This information is passed from the terminal emulator process to a 
child process through the environment variable WINDOW_ME, which is set to be the 
subwindow’s device name, for example jdev/winS. We_getmywindow reads WINDOW_ME’s 
value into mndotoname. A return value of 0 indicates success. Windowname should point to at 
least WIN_NAMESIZE characters. This information could be the handle needed for a program 
to perform some sort of special window management function not provided by the default win¬ 
dow manager. 
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This chapter describes the programming interface to a variety of separate packages that imple¬ 
ment the user interface of the tuntool layer. Because these utilities are not tied to the notions 
of tool and au6windoto as described in a previous chapter, they can be used as is, in another user 
interface system written on top of the ounwindow basic window system. For convenience, these 
utilities are associated directly with the ountool software layer. 


8.1. Full Screen Access 

To provide certain kinds of feedback to the user, it may be necessary to violate window boun¬ 
daries. Pop-up menus, prompts and window management are examples of the kind of opera¬ 
tions that do this. The fulUcreen interface provides a. mechanism for gaining access to the 
entire screen in a safe way. The package provides a convenient interface to underlying sunwin- 
doiv primitives. The following structure is defined in jutrlindudejtuntooljfuUtcretn.h: 

struct fullscreen { 


int 

fs_windowfd; 

struct 

rect fs_8creenrect; 

struct 

pixwin •f8_pixwin; 

struct 

cursor f8_cachedcur8or; 

struct 

inputmask fs_cachedim; 

Int 

fB_c achedinputnex t; 


}; 

Fejmndowfd is the window that created the fullscreen object. Fsjscreenreet describes the entire 
screen’s dimensions. Fs^izu/in is used to access the screen via the pixwin interface. The coor¬ 
dinate space of fullscreen access is the same as fsjmindowfdCo. Thus, pixwin accesses are not 
necessarily done in the screen’s coordinate space. Also, fsjscreenreet is in the window’s coordi¬ 
nate space. If, for example, the screen is 1024 pixels wide and 800 pixels high, fs_windowfd has 
its left edge at 300 and its top edge at 200, that is, both relative to the screen’s upper left-hand 
comer, then fsjscreenreet is (-300, -200, 1024, 800}. 

The original cursor, fsjcachedeursor, input mask, fs_cackedim, and the window number of the 
input redirection window, fsjcachedinputnext, are cached and later restored when the fullscreen 
access object is destroyed. 

struct fullscreen *fullscreenJnit(windowfd) 
int windowfd; 

gains full screen access for windowfd and caches the window state that is likely to be changed 
during the lifetime of the fullscreen object. Windowfd is set to do blocking I/O. A pointer to 
this object is returned although a global pointer named sunwindow will keep multiple processes 
from gaining fullscreen access at the same time. 

During the time that the full screen is being accessed, no other processes can access the screen, 
and all user input is directed to fs-'^fsjwindowfd. Because of this, use fullscreen access 
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infrequently and for only short periods of time. 

FuUsereen_destroi/ restores /»*s cached data: 

f uliscreenjdestroy(fs) 

struct fullscreen ‘^fs; 

It releases the right to access the full screen and destroys the fullscreen data object. 
Ft->f»_w%ndowfis input blocking status is returned to its original state. 


8.2. Icon Display Facility 

This section describes an icon display facility. The icon structure is simply a stylized descrip¬ 
tion of a useful class of images. Icons normally serve more to identify an object than display its 
contents. A typical use of an icon is to identify a currently unused but available tool. Another 
use might be a graphical depiction of an object, a document, database element, or resource for 
instance, that a user might 'want to point at with his mouse. The icon structure is declared in 
the file / usr/include/suntool/icon.hi 


struct icon { 



short 

ic_width; 


short 

ic_height; 


struct 

pixrect *ic_background; 

struct 

rect ic_gfxrect; 


struct 

pixrect *ic_mpr; 


struct 

rect ic_textrect; 


char 

*ic_text; 


struct 

pixfont *ic_font; 


int 

}; 

ic_flags; 


#define ICON_BKGRDPAT 

0x02 

#define ICON_BKGRDGRY 

0x04 

#define ICON.BKGRDCLR 

0x08 

#define ICON_BKGRDSET 

0x10 


lc_w{dth and ie_height describe the full size of the icon. Ic_background is an optional pattern 
with which to prepare the image background. le_gfxrect and icjextreet describe two subareas 
of the icon (icon coordinate system relative), which may overlap. Ic_mpr addresses a memory 
pixrect as described in Memory Pixrects. Icjmpr has the graphic portion of the icon, ie_text 
points to a string, and iejont a font in which to display it. The bits of iejlags are defined 
above and indicate different ways to prepare the background of the image before adding tc_mpf 
and the text: 

icon_bkgrdpat 

use iejbackground 
ICON_BKGRDGRY 

use a standard gray pattern used by the background window (this back¬ 
ground is the memory pixrect tooljbkgrd defined in 
/ usr/include/ suntool/ tooih). 

ICON_BKGRDCLR 

clear (white out) the image 
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ICON^KGRDSET 

set (solid black) the image. 

The function: 

icon_display(icon, pixwin, x, y) 
struct icon *icon; 
struct pixwin *pixwin; 

int X, y; 

displays icon offeet (*, y) from the origin of pixwin. The background is prepared according to 
icon-> ic_flagt. The graphic portion of the icon is displayed next, followed by the text; thus, if 
they overlap, the text will come out on top. 

There are no strict restrictions on the size of an icon. However, the facility becomes relatively 
pointless if the icon b too large. Non-uniform icons have esthetic and placement defects. 
Therefore, a set of standard dimensions should be provided for any particular class of icons. 
Here are the standards used by clients of tools defined in fntrf include/»untool/tool.k: 

#define TOOL JCONWIDTH 64 
#define TOOLJCOHEIGHT 64 
#define TOOL JCONMARGIN 2 

#define TOOLJCONIMAGEWIDTH 
#define TOOLJCONIMAGEHEIGHT 
#define TOOLJCONIMAGELEFT 
#dcfine TOOLJCONIMAGETOP 

#define TOOLJCONTEXTWIDTH 
#define TOOLJCONTEXTHEIGHT 
#define TOOLJCONTEXTLEFT 
#define TOOLJCONTEXTTOP 

These constants put the icon in a 64-pixel square, including a two-pixel margin all around. The 
graphics and text regions are defined relative to the size of the icon and its margin; the graphics 
area covers the whole icon inside the margin, and the text overlies the bottom 3/4 of that 
region. The TOOLJCONIMAGE* and TOOLJCONTEXT* constants hold defaults for gen¬ 
erating reasonable images when i c pf xreet and iejtextrect respectively are initialized to them. 

8.3. Pop-up Menus 

A pop-up menu is a collection of items that a user can choose among by pointing the cursor at 
the desired item. It is quickly displayed in response to a button push, remains visible as long 
as the user holds the button down, and disappears as soon as the button is released. 

Several menus can be presented at once. They appear to the user as a stack of images with the 
header of each menu visible, along with the items of the top menu in a vertical list. The user 
can bring other menus to the top by the same mechanism as choosing an item in the top menu. 

A single menu is described by the following structure defined in /usr/include/auntool/menu.h: 
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struct menu { 


int 

mjmagetype; 

caddrj 

mjmagedata; 

int 

mjtemcount; 

struct 

menuitem ‘mjtems; 

struct 

menu ‘mjiext; 

caddrj 

m_data; 


}; 

#define MENUJMAGESTRING 0x0 

Mjimagctype describes the data type of m_imagedata, Mjimagedata is a pointer to the data 
displayed in the header of the menu. MENUJMAGESTRING is the only currently defined 
image data type and is a character pointer. Mjnezt addresses the next menu in a stack; it is 
NULL if this menu is the last or only one in the stack. M_data is private data utilized by the 
menu package while displaying menus. Mjitcmt is an array of menuitemt whose length is 
m_itemeount. 

struct 
int 

caddr_t 
caddr_t 

}; 

A menuttem consists of a display token/data pair. Mi_imagctype describes the data type of 
mijimagedata, Mijimagedata is a pointer to the data displayed in this item. 
MENUJMAGESTRING is the only defined image data type and is a character pointer. 
Mi_data is private to the creator of the item. Typically, it is an identifier that differentiates this 
item from others. 

A client of the menu package constructs a stack of menus or several, for different situations by 
allocating menu structures and menuitem arrays and initializing all the fields in them. This 
involves hooking up all the data structures by setting the various pointers. An example of a 
menu set is found in Sample Tools in the panetool program. Button>down on the right mouse 
button is the standard invocation. Then when a user action initiates menu processing, the 
client calls: 

struct menuitem *menu_display(menuptr, event, iowindowfd) 
struct menu ♦♦menuptr; 

struct inputevent ‘event; 

int iowindowfd; 

Menuptr is the address of a menu pointer that points to the first or “top” menu structure in a 
menu stack. If the user causes the stack order to be rearranged, this indirection allows the 
menu package to leave the new top of the stack in *menuptr upon returning from menu_display. 
The menu package shuffles the stack’s mjnext values to rearrange the stack order. This enables 
the menu stack to be redisplayed in the order it was left in the last invocation. 

Eveni is the inputevent which provoked the menu. The location information, event-> tejocx, 
event-> ie_locy, in the event controls where the menus will be displayed. Event~>ie_code is the 
event that is treated as the “menu button;” that is, the menu is displayed until this button goes 
up. The right mouse button is the usual menu button. The left mouse button is always used 
as the accelerator to bring rear menus forward. If it wasn’t an explicit user action that pro¬ 
voked the call to menu_display, these three event fields must be loaded with the desired values 


menuitem { 
mijmagetype; 
mijmagedata; 
mi_data; 
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beforehand. 

Icwindowfd is the file descriptor for the window that is displaying the menu. It is also the win¬ 
dow that is read for user input. The event location values are relative to this window. 

Mcn«_</wp/oy currently uses the mechanism described in Fvdt Screen Aceett. A/enu_rfisp/ay tem¬ 
porarily modifies iowindowj^i input mask to allow mouse motion and buttons to be placed on 
this window’s input queue. All the menus in the stack are displayed, and there can only be one 
stack on the screen at a time. The font used for strings is that returned from pw_pfsyaopen. 
Menu_diaplay rettirns the menuitem, which was under the cursor when the user released the 
mouse button, or NULL if the cursor was not over an item. 


8.3.1. Prompt Facility 

A prompt facility is sometimes used with menus to tell the user to proceed from his current 
state. Prompting can also be done without menus. The definitions for the prompt facility are 
found in fuarf include!avmtoolf menu.h: 

struct prompt { 

struct rect prtjrect; 

struct pixfont *prt_font; 

char *prt_text; 

}; 

#definc PROMPT_FLEXIBLE -1 

Prtjrect is the rectangle in which the text addressed by prtjtext will be displayed using prt^ont. 
Only printable characters and blanks arc properly dealt with. Carriage returns, line feeds or 
tabs are not. If any of prtjrect''^ fields are PROMPTJFLEXIBLE, that dimension is automati¬ 
cally chosen by the prompt mechanism to accommodate all the characters in prt_text. 

mcnu_prompt(prompt, event, iowindowfd) 
struct prompt '•'prompt, 

struct inputevent *event; 

int iowindowfd; 

Menu_prompt displays the indicated prompt (prompt->prt_rect is iowindowfd relative), and 
then waits for any input event other than mouse motion. It then removes the prompt, and 
returns the event which ended the prompt’s existence in event. Iowindowfd is the window from 
which input is taken while the prompt is up. The fuUacreen access method is used during 
prompt display. 

8.4. Selection Management 

This section describes an interface to a aelection manager that is used to coordinate access to a 
single data entity called the current aelection. The current selection is globally accessible by any 
process, thus providing an inter-tool data exchange mechanism. 

A commoji style of operation/operand command specification is a non-modal one in which the 
operand is specified first. Ih the window system, the operand is called the aelection since it usu¬ 
ally requires that the user select something with the pointing device. A selection is highlighted 
in some way and persists until an operation removes it programmatically or the user performs 
some action that causes the selection to be removed. 
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The header file fuarjincludelsuntool/aelection.k contains the definition necessary for using selec¬ 
tions. The object that describes a selection is: 

struct selection { 


int 

seljtype. 

int 

seljltems, 

int 

seljtembytes. 

int 

sel _pubflags; 

caddrjt 

8el_privdata; 


}; 

#define SELTYPE_NULL 0 

#define SELTYPE^CHAR 1 

Sel_type indicates the type of the selection. Currently, SELTYPE_NULL (no selection) and 
SELTYPE_CHAR (ASCII characters) are the only selection types defined. Seljtems is the 
number of items in the selection data. Seljltembytes is the number of bytes each item occupies 
in the selection data. Seljpuhflags is used to contain publicly understood flags that further 
describe the selection. Sel_prtvdata is used to contain 32 bits worth of privately understood 
data that is only understood between implementations of a particular selection type. 

The selection structure is not to be confused with actual selection data itself, the characters in a 
SELTYPEjCHAR selection, for instance. 

selection_8et(scl, ^el_write, sel_clear, windowfd) 
struct selection *sel 

int (*sel^write)(); 

int (*8cl_clear)(); 

int windowfd; 

8el_writc(sel, file) 

struct selection ■•‘sel; 

FILE *file; 

8el_clear(8el, windowfd) 
struct selection *8el; 

int windowfd; 

Selection_set is used to change the current selection. Sel describes the selection. Sel_write is a 
procedure that is called to store information into the selection. Currently, only selectian_set 
calls sel_write, but in the future seljwrite might be called at any time. The selju/nte procedure 
takes as arguments sel, the selection description handed to selection_set, and file, a standard 
I/O FILE pointer. The standard I/O library is used to write the selection data to file. Win- 
dowfd is the window that is making the selection. 

Seljclear is a procedure that the selection manager would call when it wanted the selection 
currently being set to be dehighlighted. This could happen when another selection hewl been 
made. This clear feature is not currently implemented. When implemented this call could come 
at any time after returning from selection_set. 

selection_clear(windowfd) 
int windowfd; 

is called when windowfd wants to clear the current selection. Ideally, there is only one selection 
on the scfcen at a time so that the user doesn’t become confused about which operand will be 
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affected by his next command. 

Since the «d_dear feature is not currently implemented, it is the selection maker’s decision as to 
when to dehilight his selection feedback. The only existing use of the selection mechanism waits 
for the user to move his cursor out of the window that made the selection before dehilighting it. 

selection_get(sel_Tead, windowfd) 

Int (♦seljread)(); 

int windowfd; 

8eljread(sel, file) 

struct selection ^sel; 

FILE *file; 

SeUction_get is used to find out the current selection. Sdjread is a procedure that ed€ction_g€t 
calls to enable the client to retrieve the selection. Windowfd is the window that wants to find 
out about the selection. 

The ad^read procedure takes as arguments ad, the selection description of the current selection, 
and fUe, a standard I/O FILE pointer. The standard io library is used to read the selection 
data from file. Sdjread should check the type of the selection and make sure that it is a type 
with which it can deal. 


8«5. Window Management 

The procedures in this section implement common functions for managing windows. 


8.5.1. Window Manipulation 

These routines provide the standard window management user interface presented by tool win¬ 
dows: 
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•wmgr_open(toolfd, rootfd) 
int toolfd, rootfd; 

'wmgr_close(toolfd, rootfd) 
int toolfd, rootfd; 

’wmgr_move(toolfd) 
int toolfd; 

•w mgr_8tretch( toolfd) 
int toolfd; 

wmgr_top(toolfd, rootfd) 
int toolfd, rootfd; 

wmgr_bottom(toolfd, rootfd) 
int toolfd, rootfd; 

wnigr_refre3h\?indow(windowfd) 
int windowfd; 

In each of the above routines, toolfd is a file descriptor for a tool window and rootfd is a file 
descriptor for the root window. Wmgr_open opens a tool window from its iconic state to normal 
size. If the window is already open, wmgr_open does nothing. Wmgr_clote closes a too! window 
from its normal size to its iconic size. If the window is alrezuly closed, wmgr_cl 0 »e does nothing. 
Wmgr_move prompts the user to move the tool window or cancel the operation. If confirmed, 
the rest of the move interaction, including dragging the window and moving the bits on the 
screen, is done. Wmgr_streteh is like wmgr_move, but it stretches the window instead of moving 
it. Wmgrjlop places the too! window on the top on the window stack. Wmgrjbottom places the 
tool window on the bottom on the window stack. Wmgrjrefreskwmdow causes windowfd and all 
its descendant windows to repaint. 

The routine wmgT_changerect. 

wmgr_changerect(feedbackfd, windowfd, event, move, noprompt) 
int feedbackfd, windowfd; 

struct inputevent “event; 

bool move, noprompt; 

implements wmgrjmove and wmgr_itretch, including the user interaction sequence. Windowfd is 
moved (1) or stretched (0) depending on the value of move. To accomplish the user interaction, 
the input event is read from the feedbackfd window (usually the same as windowfd). The 
prompt is turned off if noprompt is 1. 

int wmgr_confirm(windowfd, text) 
int windowfd; 

char “text; 

Wmgr_confirm implements a layer over the prompt package for a standard confirmation user 
interface. Text is put up in a prompt box. If the user confirms with a left mouse button press, 
then -1 is returned. Otherwise, 0 is returned. 
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Note: The up button event is not consumed. 

The windovr management package provides menu handling code that ties all the routines in this 
subsection into the umgrjlootmenu. This provides a convenient way of getting access to the 
same menu that is presented by a tool window. If you don’t like the menu provided (you want 
to add/subtract/change menu items), define and use a new one. The routines in this section 
should be all you need to put together a functionally similar window manipulation interface. 

struct menu *wmgr_toolmenu; 

■w mgr_setupmenu(toolfd) 
int toolfd; 

wmgr_hand!etoolmenuitem(menu, mi, toolfd, rootfd) 
struct menu *menu; 
struct menuitem *mi; 

int toolfd, rootfd; 

To use the default tool menu, call wtngr_tetupmenu just before you put up tomgrjtoolmenu. 
Wmgr_tetupmena arranges the menu items depending on the tool state (iconic vs. normal). 
Passing the menu item returned from menu_duplay to wmgr_handletoolmenuttem causes the 
appropriate menu action to be done. As an example, refer to the Pane Tool code provided in 
panetool.c in appendix B. 

8.5.2. Tool Invocation 

The routines in this section provide tool invocation and default position control. 

#define WMGR.SETPOS -1 

■wragr_figuretoolrect(rootfd, rect) 
int rootfd; 

struct rect *rect; 

■wmgr_figureiconrect(rootfd, rect) 
int rootfd; 

struct rect *rect; 

These routines allow windows to be assigned initial positions that don’t pile up on top of one 
another. The rootfd window maintains a “next slot’’ position for both normal tool windows and 
icon windows (see timgr_jctrectaUoc below). These procedures assign the next slot to the rect if 
rect-^r^left or re<lt->rJtop is equal to \VMGR_SETPOS. A new slot is chosen and is then 
available for the next window with an undefined position. 

These procedures also assign a default width and height if WMGRJSETPOS is given, again for 
both normal (tool) and iconic rects. Wtngr_figuretoolrect currently assigns tool window slots 
that march from hear the top middle o^ the screen towards the bottom left of the screen. It 
assigns a window sire correct for an 80-column by 34-row terminal emulator window. 
Wmgr_figur€iconrect currently assigns icon slots that march from the left bottom towards the 
right of the screen. It assigns icon sizes that are 64 by 64 pixels. 
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wmgr_forktool(programname, otherargs, rectnormal, recticon, iconic) 
char * program name, *otherargs; 

struct rcct *rectnormal, *recticon; 

int iconic; 

is used to fork a new tool that has its normal rectangle set to rectnormal and its icon rectangle 
set to rccficen. If iconic is not zero, the tool is created iconic. Programname is the name of the 
file that is to be run and otherargs is the command line that you want to pass to the tool. A 
path search is done to locate the file. Arguments that have embedded white space should be 
enclosed by double quotes. 


8.5.3. Utilities 

The utilities described here are some of the low level routines that are used to implement the 
higher level routines. They may be used to put together a window management user interface 
different from that provided by tools. If a series of calls is to be made to procedures that mani¬ 
pulate the window tree, the whole sequence should be bracketed by v»n_loekdata and 
winjunlockdata, as described in The Window Hierarchy. 

wmgr_completechanger^ct(windowfd, rcctne^, rectoriginal, parentprieft, parentprtop) 
int windowfd; 

struct rect *rectnew, *rectoriginaI; 

int parentprleft, parentprtop; 

docs the work involved with changing the position or size of a window’s rect. This involves sav¬ 
ing as many bits as possible by copying them on the screen so they don’t have to be recom¬ 
puted. Wmgr_completechangerect would be called after some programmatic or user action deter¬ 
mined the new window position and size in pixels. Windowfd is the window being changed. 
Rectnew is the window’s new rectangle. Rectoriginal is the window’s original rectangle. 
Parentprleft and parentprtop are the upper-left screen coordinates of the parent of windowfd. 

wmgr_winandchildrenexposed(pixwin, rl) 
struct pixwin *pjxwin; 

struct rectlist '^rt; 

computes the visible portion of pixwin->pw_clipdata.pwcd_windowfd and its descendants and 
stores it in rl. This is done by any window management routine that is going to try to preserve 
bits across window changes. For example, wmgr_completeehangereet calls 
wmgr_winandchildrenexposed before and after changing the window size/position. The intersec¬ 
tion of the two rectlists from the two calls arc those bits that could possibly be saved. 

wmgr_chSngelevel(windowfd, parentfd, top) 
int windowfd, parentfd; 

bool top; 

moves a window to the top or bottom of the heap of windows that are descendants of its 
parent. Windowfd identifies the window to be moved; parentfd is the file descriptor of that 
window’s parent, and fop controls whether the window goes to the top (TRUE) or bottom 
(false). Unlike wmgrjtop and wmgrjbottom, no optimization is performed to reduce the 
amount of repainting. Wmgr_changelevel is used in conjunction with other window rearrange¬ 
ments, which make repainting unlikely. For example, wmgr_close puts the window at the bot¬ 
tom of the window stack after changing its state. 
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#define WMGRJCONIC WUF.WMGRl 

•wmgr_is'wmdowopen('windo-wfd) 
int windowfd; 

The user data of windowfd reflects the state of the window via the WMGRJCONIC flag. 
WUF_WMGR1 is defined in Juarjincludejtunwindowjxjoinjioetl.h and WMGRJCONIC is 
defined in futrfincludelsuntool/wmgr.h, Wmgr_iswindou!open tests the WMGRJCONIC flag 
(see above) and returns TRUE or FALSE as the window is open or closed. 

The rootfd window maintains a “next slot” position for both normal tool windows and icon win¬ 
dows in its unused iconic rect data. Wmgr__setrectttlloc stores the next slot data and 
wmgr_getreeialloe retrieves it: 

wmgr_5etrectalloc(rootfd, tooljeft, tooljop, iconjeft, iconjop) 
int rootfd; 

short tooljeft, tooljop, iconjeft, iconjop; 

wmgr_getrectalloc{rootfd, tooljeft, tooljop, iconjeft, iconjop) 
int rootfd; 

short *toolJeft, *toolJop, *iconJeft, *iconJop; 

If you do a wmgr_setreetalloc, make sure that all the values you are not changing were retrieved 
with wmgr^etreetttlloe. In other words, both procedures affect all the values. 
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Appendix A 


Rects and Rectlists 


This appendix describes the geometric structures used with the sunwindow layer and a full 
description of the operations on these structures. Throughout sunwindow, images are dealt with 
in rectangular chunks. Where complex shapes are required, they are built up out of groups of 
rectangles. A rcct is a structure that defines a rectangle. A reetliot is a structure that defines a 
list of rects. 

The header files rect.h and reetlist.k are found in /usr/include/sunwindow/. The library that 
provides the implementation of the functions of these data types are part of 
/usr/lib/libsunwindow.a. 

Although these structures are presented in terms of sunwindow usage with pixel units, they are 
really separate and can be thought of as a rectangle algebra package. Any application that 
needs such a facility should consider using rects and rectlists. 

A«l. Rects 

The rect is the basic description of a rectangle, and there are macros and procedures to perform 
common manipulations on a rect. 

#define coord short 

struct rect { 
coord 
coord 
short 
short 

}; 

The rectangle lies in a coordinate system whose origin is in the upper left-hand corner and 
whose dimensions are ^ven in pixels. 


rjeft; 

rjtop; 

r_width; 

rjheight; 


A. 1.1. Macros on Rects 

The same header file defines some interesting macros on rectangles. To determine an edge not 
given explicitly in the rect; 
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^define rect_right(rp) 

^define rect_bottom(rp) 
struct rect *rp; 

returns the coordinate of the last pixel ivithin the rectangle on the right or bottom, respectively. 
Useful predicates returning TRUE or FALSE are: 

#define bool unsigned 

#define TRUE 
#define FALSE 

rect_isnull(r) 
rectjnc ludespoint(r ,x ,y) 
rect_equal(rl, r2) 
rect_includesrcct(rl, r2) 
rect_intersectsrect(rl, r2) 
struct rect *r, *rl, *r2; 

coord X, y; 

Macros which manipulate dimensions of rectangles are: 

rect_construct(r, x, y, w, h) 
struct rect '^r; 

int X, y, w, h; 

This fills in r with the indicated origin and dimensions. 

rect_marginadjust(r, m) 
struct rect ♦r; 

int m; 

adds a margin of m pixels on eeurh side of r; that is, r becomes 2*m larger in each dimension. 

rect_passtoparent(x, y, r) 
rect_passtochild(x, y, r) 
coord X, yj 

struct rect ■^r; 

sets the origin of the indicated rect to transform it to the coordinate system of a parent or child 
rectangle, so that its points are now located relative to the parent or child’s origin. X and y are 
the origin of the parent or child rectangle within ita paurent; these values are added to, or 
respectively subtracted from, the origin of the rectangle pointed to by r, thus transforming the 
rectangle to the new coordinate system. 


1 

0 

r’s width or height is 0 

(x,y) lies in r 

ri and r.? coincide exactly 

every point in r2 lies in ri 

at least one point lies in both ri and r2 


A.1.2. Procedures and External Data for Rects 

A null rectangle, that is one whose origin and dimensions are all 0, is defined for convenience: 

extern struct rect rect_null; 

The following procedures are also defined in rect.h; 

struct rect rect_bounding^rl, r2) 
struct rect *rl, *r2; 

This returns the minimal rect that encloses the union of ri and r2. The returned value is a 
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struct, not a pointer. 

rect_intersection(rl, r2, rd) 
struct rect *rl, ♦r2, *rd; 

computes the intersection of ri and r8, and stores that rect into rd. 

bool rcct_clipvector(r, xO, yO, xl, yl) 
struct rect *r; 

coord *x0, *y0, *xl, *yl; 

modifies the vector endpoints so they lie entirely within the rect, and returns FALSE if that 
excludes the whole vector, otherwise it returns TRUE. 

Note: This procedure should not be used to clip a vector to multiple abutting rectangles. It 
may not cross the boundaries smoothly. 

bool rect_order(rl, r2, sortordcr) 
struct rect *rl, *r2; 

int sortorder; 

returns TRUE if rl precedes or equals rS in the indicated ordering: 

#definc RECTSjrOPTOBOTTOM 0 

#define RECTS30TTOMTOTOP 1 

#define RECTS.LEFTTORIGHT 2 

#define RECTS_RIGHTTOLEFT 3 

Two related defined constants are: 

#define RECTS.UNSORTED 4 

indicating a “donVcare" order, and 

#deflne RECTS_SORTS 4 

giving the number of sort orders available, for use in allocating arrays and so on. 

A.2. Rectliats 

A rectliat is a structure that defines a list of rects. A number of rectangles may be collected into 
a list that defines an Interesting portion of a larger rectangle. An equivalent way of looking at 
it is that a large rectangle may be fragmented into a number of smaller rectangles, which 
together comprise all the larger rectangle's interesting portions. A t 3 rpical application of such a 
list is to define the portions of one rectangle remaining visible when it is partially obscured by 
others. 
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struct rectlist { 

coord rLx, rl_y; 

struct rectnode *rl_head; 

struct rectnode ‘rljtail, 

struct rect rl_bound; 

}; 

struct rectnode { 

struct rectnode ♦m_next; 

struct rect rn_rect,' 

}; 

Each node in the rectlist contains a rectangle which covers one part of the visible whole, along 
with a pointer to the next node. Rljbound is the minimal bounding rectangle of the union of all 
the rectangles in the node list. All rectangles in the rectlist are described in the same coordinate 
system, which may be translated efficiently by modifying rl_x and f/_y. 

The routines that manipulate rectlists do their own memory management on rectnodes, creating 
and freeing them as necessary to adjust the area described by the rectlist. 


A.2.1. Macros and Constants Defined on Rectlists 

Macros to perform common coordinate transformations are provided: 

rl_rectoflset{rl, rs, rd) 
struct rectlist ’^rl; 

struct rect *rs, ♦rd; 

copies rs into rd, and then adjusts rd'i origin by adding the offsets from r/. 

rl_coordoflf8et(rl, x, y) 
struct rectlist ♦rl; 

coord x, y; 

offsets z and y by the offsets in r/. For instance, it converts a point in one of the rects in the 

rectnode list of a rectlist to the coordinate system of the rectlist*s parent. 

Parallel to the macros on rcct’s, we have: 

rl_passtoparent(x, y, rl) 

rl_pas5tochild(x, y, rl) 
coord X, y; 

struct rectlist ♦rl; 

which add or subtract the given coordinates from the rectlist’s rl_x and rl_j/ to convert the rl 

into its parent’s or child’s coordinate system. 


A.2.2. Procedures and External Data for Rectlists 

An empty rectlist is defined, which should be used to initialize any rectlist before it is operated 
on: 

extern struct rectlist rl_nuli; 
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Procedures are provided for useful predicates and manipulations. The following declarations 
apply uniformly in the descriptions below: 

struct rectlist *rl, ♦rll, *rl2, *r!d; 

struct rect ■•‘r; 

coord X, y; 

Predicates return TRUE or FALSE. Refer to the following table for specifics. 


Table A-1: Rectlist Predicates 



Macro 

Returns TRUE if 

rl_empty(rl) 

Contains only null rects 

rl_equal(rll, rl2) 

The two rectlists describe the same space identically — 
same fragments in the same order 

rl_incIudespoint(rl,x,y) 

(z, ]/) lies within some rect of rl 

rl_equalrect(r, rl) 

rl has exactly one rect, which is the same as r 

rl_boundinter8ectsrect(r, rl) 

Some point lies both in r and in rf s bounding rect 


Manipulation procedures operate through side-effects, rather than returning a value. Note that 
it is legitimate to use a rectlist as both a source and destination in one of these procedures. The 
source node list will be freed and reallocated appropriately for the result. 
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Refer to the following table for specifics. 


Procedure 

Effect 

rl_intersection(rll, rl2, rid) 

Stores into rid a rectlist which covers the intersection 
of rll and fl8. 

rI_union(rll, rl2, rid) 

Stores into rid a rectlist which covers the union of rll 
and rl8. 

rl_difference(rll, rl2, rid) 

Stores into rid a rectlist which covers the area of rll 
not covered by rlS 

rl_coalesce(rl) 

An attempt is made to shorten rl by coalescing some of 
its fragments. An rl whose bounding rect is completely 
covered by the union of its node rects will be collapsed 
to a single node; other simple reductions will be found; 
but the general solution to the problem is not attempt¬ 
ed. 

rl_sort(rl, rid, sort) 
int sort; 

rl is copied into rid, with the node rects arranged in 
sort order. 

rljrectinter8ection(r, rl, rid) 

rid is filled with a rectlist that covers the intersection 
of r and rl. 

rIjrectunion(r, rl, rid) 

rid is filled with a rectlist that covers the union of r 
and rl. 

rl_rectdifference(r, rl, rid) 

rid is filled with a rectlist that covers the portion of rl 
which is not in r. 

rl_initwithrect(r, rl) 

Fills in rl so that it covers the rect r 

rl_copy(rl, rid) 

Fills in rid with a copy of rl. 

rl_free{rl) 

Frees the storage allocated to rl. 

rl_normalize(rl) 

Resets rfs offsets {rl_z, rl_j/) to be 0 after adjusting the 
origins of all rects in rl accordingly. 
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This appendix contains sample tool code for writing your own tools. Code is provided for the 
graphics window {gfztooLe), which produces a shell subwindow and an empty subwindow in 
which graphics programs can run, the pane tool {panctool.c), which produces multiple subwin¬ 
dows, the option tool (optiontooLc), which tests the option subwindow library, and the icon tool 
(ieontooic), which is a bitmap editor for painting icons and cursors. The source files for these 
and other tools are found in juar!tuntoolf arej Hool.c. 


B.l. gfxtool.c Code 

Code for gfxtooLc follows. 

#ifndef lint 

ststie char seesidi] — ’’O()il)sfxtool.e 1.8 83/10/18 Sun Micro”; 

#endif 

/* 

• Sun Mierotystenw, Inc. 

•/ 

/• 

• Overview: Graphiea Window: A shell subwindow and an empty 

• subwindow in which graphics programs can run. 

•/ 

#include <qra/type8.h> 
fjlinclude <rignal.h> 

^include ”pixreet/pixreet.h” 

#inc]ude ’’pixrect/pixfont.h* 

#ittelude ” pixreet/pr.util.h” 

^include ” pixrect/memvar.h” 

#inctude "sunwindow/rect.h” 

#inelude *sunwindow/reetli8t.h” 

^include "sunwindow/pixwin.h” 

^include "sunwindow/win^truct.h” 

#include * 8unwindow/win_environ.h” 

#include "suntool/icon.h” 

^include "suntool/tool.h” 

^include ”suntool/emptysw.h” 

#include "suntool/ttysw.h” 

static short ic_image[256|v{ 

^include ”gfxtool.icon* 

); 

mpr^atic(gfxic_mpr, 64, 64, 1, icjraage); 
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static struct icon icon {64, 64, (struct pixrect ‘jO, 0, 0, 64, 64, 
&gfxic_mpr, 0, 0, 0, 0, (char *)0, (struct pixfont *)0, 
ICON_BKGRDGRY}: 

static int sigwinchcatcherO, sigehldcatcherO; 

static struct tool *tool; 

gfxtool_niain(argc, argv) 
int argc; 
char ‘‘argy; 

char *toolname — "Graphics Tool 1.0”; 
struct toolsw *ttysw, *emptysw; 
char name[WIN_NAMESIZE]; 


o 


* Create tool window 

•/ 

tool - tooLcreate(toolname, TOOLJ4AMESTRIPE|TOOL_pOUNDARYMGR, 
(struct rect *)0, &icon); 

/• 

* Create subwindows 

•/ 

ttysw »» tty8w_createtool8ubwindow(tool, "ttysw", 

TOOL_SWEXTENDTOEDGE, 200); 
emptysw -■ esw createtool8ubwindo'w(tool, "emptysw”, 

TOOL SWEXTENDTOEDGE, TOOL_SWE)CrENDTOEDGE); 

/• “ . , 

* Setup gfx window environment value. 

•/ 

win_fdtoname(emptysw- > ts.windowfd, name); 
we_petgfxwindow(narae); 

/* 

« Install tool in tree of windows 

•/ 

Bigna!(SIGWINCH, sigwinchcatcher); 

8ignal(SIGCHLD, sigchldcatcher); 
tool_in8tall(tool); 

/• 

* Start tty process 

*/ 

if {tty8w_fork(tty8w->ts_data, + + argv, &ttyBw->t8jo.tioJnputmask, 

&ttysw->t8_io.tio_outputma8k, &tty8w->t8_io.tio_exceptmask) ■■■■ -1) { 
perror("gfxtool”); 
exit(l): 

} 

/• 

« Handle input 

•/ 

tooL8elect(tool, 1 /♦ means wait for child process to die*/); 

h 

* Cleanup 

*/ 

tool_destroy(tool); 

exit(O); 
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eigchldsatcherO 

too5^^igchld(tool); 

} 

static 

sigwinchcatcherO 

{ 

tool_?i 5 winch(tool)j 

} 


B.2. panetooLc Code 

Code for the panetool.c followa. 

#ifndef lint 

static char sccsidj) ’’©(^fjpanetool.c 1.8 83/10/18 Sun Micro”; 

^endif 

/* 

• Sun Microsystems, Inc. 

•/ 

/* 

• Overview: Pane Tool: Sample program to illustrate multiple 

• subwindows. 

•/ 

lfl> include <[^B/types.h> 

^include <qr8/time.h> 

#include <8ignal.h> 

^include "pixrect/pixrect.h" 

^•include ”pixreet/pixfont.h” 

^include "sunwindow/reet.b” 
ijlinelude "sunwindow/rectlist.h” 

^include ” sunwindow/pixwin.h” 

^include "sunwindow/winjnput.h" 

^include "sunwindow/winjtruct.h" 

^include "suntool/icon.h” 

^include "suntool/tool.h” 

^include "suntool/msgsw.h” 

^include "suntool/menu.h” 

static int sigwineheatcber(); 

static struct tool *tool; 

static char charbuf{4]; 

struct menuitem m3_item8[) " { MENUJMAGESTRING, "Menu Item , 0}; 

struct menu m3_menubody «■ { v • „ i 

MENUJMAGESTRING, "M3”, 8izeof(m3Jtems) / azeof(struct menuitem), ro3jtems, 0, 0 }; 

struct menuitem ra2Jtems(j =• { MENUJMAGESTRING, "Menu Item", 0}; 
struct menu m2_menubody •“ { 

MENUJMAGESTRING, "M2", siaeof(m2Jtem8) / 8iseof(8truct menuitem), 
m2Jtem8, &m3_menubody, 0}; 

struct menuitem mljtemsl] “ { hffiNUJMAGESTRING, "Menu Item”, 0}; 
struct menu ml_menubody “ { 
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MENUJMAGESTRING, "Ml*, 8iseof(mlJtems) / riseof(atruct menuitem), 
mljtems, &m2_menubody, 0}; 
struct menu *stacklmenutop = &mljnenubody| 

struct menuitem m4_itemsP =» { MENUJMAGESTRING, "Menu Item", 0}; 
struct menu m4_menubody = { 

MENUJMAGESTRING, "M4", 8i2eof(m4Jtcm8) / 8ijeof{8truct menuitem), 
m4jtema, 0, 0 }; 

struct menuitem mSJtemsQ “ { MENUJMAGESTRING, "Menu Item”, 0}; 
struct menu m5_menubody { 

MENUJMAGESTRING, ”M5", 8i*eor(m5Jtem8) / m»eof(8truct menuitem), 
mSJtems, &m4_menubody, 0); 

struct menuitem mSjtemsQ " ( MENUJMAGESTRING, "Menu Item”, 0); 
struct menu m8_menubody ■— { 

MENUJMAGESTRING, "M6”, siwoftmSJtems) / si*eor(struct menuitem), 
mSjtems, &m5_menubody, 0}; 
struct menu *8tack2menutop ~ &m6_menubody; 
int menutoggle; 

main(arKC, argv) 
int arge; 
char ••argv; 

char •toolname — "Pane Tool 1.0 (A sample tool)”; 
struct toolsw epaneNW, *paneNE, epaneSW, *paneSE; 
extern struct pixfont •pt_pyo‘, 

/* 

• Create tool window 

•/ 

tool “ tool_create(too!name, TOOL_NAMESTRlPEjTOOL_pOUNDARYMGR, 
(struct rect *) 0, (struct icon *) 0); 

/* 

• Create rasg subwindows 

•/ 

paneNW ■■ m8gsw_createtoolsubwindow(tool, "paneNW*, 

100,100, "Raw keyboard input”, pfjqrs); 
paneNE — m8gsw_createtoolsubwindow(tool, "paneNE", 
TOOLJSWEXTENDTOEDGE, 100, 

"Key input here redirected to NW sub window”, pf_8y8); 
paneSW «- m8gsw_createtoolBubwindow(tool, "paneSW”, 

100, TOOL_SWEIXTENDTOEDOE, "Display alternating menu stacks”.pLsys); 
paneSE ~ msg8w_ereatetoolsubwindow(tool, "paneSE”, 

TOOLJSWEXTENDTOEDGE, TOOLJSWEXTENDTOEDGE, 

"Try moving sub window boundariss”, pf_^B); 

/• ' , . 

* Raw input and flushing 

*/ 

{ 

struct inputmask im; 
int paneNWjseleeted(); 

inputJmnull(& im); 

im.imjlags |” IMJJNENCODBD; 

win_8etinputmask(paneNW->ts_windowfd, &im, &im, WINJ'JULLLINK); 
paneNW->tsJo.tio_selected =» paneNWjselected; 

} 

/* 

* Input redirection 
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•/ 

{ 

struct inputmask im; 

win ff etinputmaskfpaneNEl- >ta_windowfd, &im, 0); 
wm_setinputmask(paneNEl->t8_windowfd, &im, (struct Lnputmask •) 0, 
win fdtonumber(paneNW- > t8_windowfd)); 

} 

/• 

* Multi menu stacks 

•/ 

{ 

struct inputmask im; 
int paneSWjelectedQ; 

input_imnull(&im); 

win_setinputeodebit(&im, MENU_PUT); 

win_8etinputraa8k{paneSW*>ts_windowfd, &im, &im, WIN_NULLLINK); 
paneSW->tsJo.tioj>eleeted -■ paneSWjelected; 

} 

/• 

« Install tool in tree of windows 

... 

eisnal(SIGWINCH, sigwinchcatcher); 

tooUnstall(tool); 

/• 

* Handle input 

•/ 

toolj!elect(tool, 0); 

/* 

* Cleanup 

*/ 

tooLdeetroy(tool); 

exit(O); 

} 

paneNW_^eIected(msgsw, ibits, obits, ebits, timer) 
struct msgsubwindow *msgsw; 
bt *ibits, *obite, *ebits; 
struct timeval **timer; 

{ 

struct inputevent event; 
int error; 

error — input_readevent(msgaw->msg_windowfd, &event); 
if (error < 0) { 

perror("panetool’'); 

return; 

) 

charbuf|0] — ’c’; 
charbuf[l] — 

chaTbuf[2j ^ (char) event.ie_code&0X7f; 
charbuflsj - ’ 

msg8w_petstring(msg8w, charbuf); 

*ibit8 •obits + ‘ebits + 0; 


paneSW_8elected(m8gsw, ibits, obits, ebits, timer) 
struct msgsubwbdow ‘msgsw; 
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int *ibits, *obit3, ♦ebits; 
struct timeval ••timer; 

{ 

struct inputevent event; 
int error; 

extern struct menuitem •menu_di8play(); 

error = input_readevent(msg8W->msg_wmdowfd, &event); 
if (error < 0) { 

perror(” panetool"); 
return; 

(void) menu_display((menutoggle)? &:stacklmenutop; &stack2menutop, 
&event, m8g8W->m8g_windowfd); 
menutoggle «■ Imenutoggle; 

•ibits “ ‘obits + ‘ebits + 0; 

} 

static 

sigwinchcatcherO 

{ 

tool_eigwinch(tool); 

} 



B.3. optiontool.c Code 

Code for the optiontooLc follows. 

^ifndef lint 

static char sccsidQ ■■ "©((jlloptiontool.c 1.10 84/01/17 Sun Micro"; 
#endif 

/• 

• Sun Microsystems Inc. 

•/ 


* optiontool: test optionsw library 

•/ 

^include <Btdio.h> 

^include <8untool/tool3s.h> 

^include <suntooI/optionBw.h> 

static struct tool ‘tool; 

static char ‘name ■■ "Option Tool 1.1"; 

static struct toolsw ‘tsw; 

static caddr_t osw; 

static struct pixwin opt_pixwin; 

static caddr_t items [32]; 

static struct pixfont ‘font; 
static struct rect r; 



static unsigned dump_glyph[16] = { 

0x00002000, 0x00007000, OxOOOODSOO, 0x00018000, 
0x00030800, Ox00060ClF, 0x30001819, 0x00183019, 
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0x033070lF, OXOOEOC87F, Ox0031847F, OxO29B0261, 
0x07EF6FED, 0xlFE149012, 0x7FF89012, 0xFFF8600C 

static mpr_static(dump_pr, 32, 16, 1, dump_glyph); 

static struct typed_pair title " { IM_TEXT, "Option Subwindow Demo }; 

static struct typed_pair confirm_Jabel = { IM_TEXT, "Quittable” }; 

static struct typecLpair quitjabel ■- { IM_TE!XT, "Quit" }; 

static struct typed_pair verbose_label " { IM_TE!XT, "Verbose” }; 

static struct typcd_pair dumpjlabel “ { IM_GBAPinC, (caddr_t)&dump_pr}; 

static struct typcdjpaar x_label — { IM_TEXT, "Flag X* }; 

static struct typed_pair y_label ■■ { EMJTEIXT, "Flag Y" }; 

static struct typed_p^ { IM_TEXT, "Flag Z" }; 

static struct typcd_pair tljabel « { IM_TEXT, "Type here* }; 

static struct typed_pair t2_label ™ { IM_TEXT, "Secret" }; 

static struct typed_pair t3_label ■■ { IM_TEXT, "line I"}; 

static struct typedjjwr t4_label “ { IM_TEXT, "line 2"}; 

static struct typed_pair txtcmd_label { IM_TEXT, "Report Text" }; 

static struct typedjmr enura_label " { IM_TEXT, "Choose" }; 
static char schoice_values[J ™ { "Zero”, "One", "Many , 0 }; 

static struct typedjair enum_choices ■■ { IMJTEIXTVEC, (caddr_t)choice_value8 }; 

static int n, 

confirmed “ FALSE, 

remove_whieh, 

chooeer(), 

eonfirmer(), 

dumper(), 

quitter(), 

reporterO, 

sigwinchedQ, 

verbose, 

verboBsr(), 

texterO; 

FILE esysout « stderr; 

int remove djtems; 

mainQ 

{ 

struct item_place pj 

/* 

* Create tool window 

•/ 

tool -■ tooL.create(name, TOOLJ'JAMESTRIPE, NULL, NULL); 


• Create subwindow and fill it out 

•/ 

tsw ■■ optsw createloolsubwindow(tool, "optsw”, 

TOOL.SWEXTENDTOEDGE, TOOL_SWEXTENDTOEDGE): 
osw ™ t8W->t8_data; 
n — Oj 

items[n+ +) “ optswJabel(osw, &title}; 

itemsln-h + ] “ optsw_bool(o8w, &confinn_label, FALSE, confirmer); 
item8[n+ + j ”■ optsw_command(o5W, &quit_label, quitter); 
items(n4- + ] ■■ opt8W_bool(o8w, &verbose_label, FALSE, verboser); 


Revision D 7 January 1984 


B-7 



Sample Tools 


SunWindows Reference Manual 


item8[n+ + ] •» optsw_command(osw, &dump_label, dumper); 

items|n+ + ] •- optsw_enum(osw, &enumjabel, &enum_choices, 0, 0, chooser); 

items|n+ + j “ optsw_bool(o8w, &:x_label, TRUE, reporter); 

iterr}s(n+ +) ™ optsw_bool(osw, &y_label, FALSE, reporter); 

item8(n+ +1 “ optsw_bool(osw, fcO^bel, TRUE, reporter); 

item8[n+ + ) ™ opt 5 w_text(o 8 w, &tl_label, "A text parameter”, 0, NULL); 

jtems(n+ + j =■ opt8w_text(o8w, &t2_Jabei, "Shhhhh...”, OPTJTEXTMASKED, NULL); 

remove_which ■= n; 

items(n+ + ] — optsw_text(osw, &t3Jabel, 0, NULL); 

items(n+ + ] ■» opt8w_text(osw, &t4Jabel, 0, NULL); 

items[n-f + ] •" opt8w_coramand(oaw, &txtcmd_label, texter); 

rect_eonstruct(&p.rect, 128, 12, -1, -1); /• pixel positioning */ 

p.ilxed.x TRUE; p.fixed.y ■■ TRUE; 
optsw_8etplace(o8w, ite!ns|0], &p, FALSE); 

p.rect.rjeft «■ opt8w_coltox(o8w, 0); /• character positionmg •/ 

p.rect.r_top ■■ -1; 
p.fixed.y ™ FALSE; 

optsw_8etplace(o8w, items|l], &p, FALSE); 

removed_items opt8w_removeitem8{o8w, items)remove_which], 2, FALSE); 


/* 

• Install toot in tree of windows 

•/ 

8ignal(SIOWINCH, sigwinched); 
win_in8ert(tool- > tl_windowfd); 


/• 

* main loop 

*/ 

tool_8elect(tool, 0); 


/• 

* Cleanup 

*/ 

tool_destroy(tool); 

exit{0); 

} 

static 

sigwinchedO 

{ 

toolj3igwinch(tool); 

} 


static 

confirmer(BW, ip, value) 
caddr_t sw; 

caddr_t ip; 

int value; 

{ 

int result; 

confirmed = value; 
if (verbose) { 

printf(” Confirmation set to %d\n”, confirmed); 

} 
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static 

reporter(8w, ip, value) 
caddr_t aw; 

caddr_t ip; 

int value; 

{ 

int result; 
int count; 

count ■■ (int)optsw_getvalue(itemB[8l, feresult) + 
(int)opt8W_£etvalue(item8l7], &reault) + 
(intjoptswjetvalue^itemajsj, ftreault); 
if (count 3) { 
count — 2; 

optsw setvalue(BW, itemB[5], count); 

} 

static 

chooser(sw, ip, value) 
caddr_t sw; 

caddr.t ip; 

int value; 

{ 

int result; 
if (verbose) { 

printf(" Choice set to %d\n", value); 

} 

} 

static 

dumper(sw, ip) 
caddr_t sw; 

caddr_t ip; 

{ 

int result; 
if (verbose) { 

optBW„dump8w(Btdout, sw, TRUE); 

} 

} 


static 

quitter(sw,ip) 
caddr_t sw; 

caddr.t ip; 

{ 

int result; 

if (verbose) { 

printf("Quit invoked\n”); 

} 

if (IconUrmed) { 

if (verbose) { 

printfC but not confirmed.\n"); 

} 


Revirion D of 7 January 1884 


B-9 



Sample Tools 


Sun Windows Reference Manual 


return; 

) 

tool_done(tool); 


static char bufl[1024]; 

static char buf2jl024]; 

static struct string_buf strl — { 1024, bufl }; 
static struct string_buf 8tr2 — { 1024, buf2 }; 


static 

texter(sw, ip) 
caddr_t sw; 
caddr_t ip; 

{ 

int result; 


} 


if (verbose) { 

result ™ optsw_getva!ue(iteins(9], &strl); 
result opt8w_getvalue(items|10|, &8tr2); 
switch (optsw_getYslue(item8|5], &result)) { 
case 0: printfCMum’s the word.\n'’); 

break; 

case 2: printfCPirst field: %s\n’’, bufl); 

case 1: printfC Second field: %s\n’', buf2); 

} 

if (removed_item8 I— 0) { 

opt8Wjre8toreitems(o8w, item8[remove_which], 

removedjtems, TRUE); 


removedjtems 


} else { 


removeditems 


} 


0 ; 

opt8w_reinoveitems(osw, itemsfremove.which], 
2, TRUE); 




static 

verboser(sw, ip, va!) 
caddr_t sw, val; 

caddr_t ip; 

{ 

verbose (int) val; 

} 


B.4. icontool.c Code 

Code for the icontool.c follows. 

#irndef lint 

static char sccsidU “ '’®(#)icontool.c 1.6 84/01/18 Sun Micro”; 
fendif 

/* 

* Sun Microsystems Inc. 

* 

• icontool: bitmap editor for icons & cursors 


'/ 
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^include <suntool/tool_Ji8.h> 

^include <sy8/stat.h> 

^[liricluco <stdb.h> 

^include <errno.h> 

^include "patches.h” 

^include <suntool/msgaw.h> 

^include <suntool/optionsw.h> 

extern char •sys.errlistH; 
extern int ermo; 

^define ICONIC 1 

#deflne ICON.SIZE 8 

fdefine CURSOR 0 

#define CURSOR_SIZE (ICONJSIZE * 4) 




#deflne MSGJIEIGHT 24 

fjtdeiine PROOF_SIDE 06 

^deRnt PROOF_MARGIN 18 

#define OPTIONSJHEIGHTPROOF^SIDE 

#define CANVASJ)ISPLAY(CURSOR_SIZE • 16) 

#de6ne CANVASJMARGIN 16 

#define CANVAS.SIDE (CANVASJIISPLAY + 2 • CANVAS_MABGIN) 
#define BIG 2048 

static u_int icon^array|128|; 
ropr_Btatic(icon_pr, 64, 64, 1, ieon_arrsy); 
static u_int new_cur8or_array[8j; 
mpr_static(new_cur8or^r, 16,18, 1, new_cursor_array); 
static struct cursor new_curBor — { 

0 , 0 , 

PDCSRC ‘ PDCJJST, 

&new_cursor_pr 

}: 


static u_int main_cur8or_array[8j ™ { 

OxCOOOEOOO, OxFOOOF800, 
OxFCOOFOOO, 0x00001800, 
OxlSOOOCOO, OxOCOOOeOO, 
0x06000300, 0x03000100 


mpr_8tatic(main_cur8or_pr, 18, 16, 1, main_cursor_array); 
static struct cursor main_cur8or — { 


0 , 0 , 

PIX_SRC I PEXJDST, 
&main„cur8or_pr 


}; 


general tool area •/ 

^include " icontooldcon” 
mpr^atic{my_icon_pr, 64, 64, 1, icon_data); 
static struct icon my jeon »■ { 

TOOL jeONWIDTH, TOOL JCONHEIGHT, NULL, 
{0, 0, TOOLjeONWIDTH, TOOLJCONHEIGHT}, 
&my icon_pr, {0, 0, 0, 0}, NULL, NULL, 0 

}; 
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static char tool_name|| »» "Icon Tool 1.0”| 

static struct rect tool_rect; 

static struct tool *tool; 

static sigwinched(); 



/• error message area •/ 

static struct toolsw •msgjsw; 
struct msgsubwindow *msw; 


/• painting area •/ 

static struct toolsw •canvas.sw; 
static struct pixwin *canvas_pixwin; 
static struct pixrect *canvas_pr; 
static struct pixrect *fill_pr; 
static int (•eanva8_reader)(); 

static canva8_sighandler(]; 

static canvaa^elected(); 

static canvae_bMereader(); 

static canvas_tracker(); 

static set_eanvas_tracker(); 

static reset_canvas_reader{); 

static canvas_feedback(); 

static wait_legaljtnouse(); 


/• result-display area */ 

static struct toolsw *proof_Bw; 
static struct pixwin *proof_pixwin; 
static struct pixrect •proof_pr; 
static proofjsighandler(); 



/* commands and options area •/ 

static struct toolsw •options_pw; 
caddr_t osw; 

/• labels for items in the order they occur; enum values appear below *f 
caddr_t modejtem; 

struct typed_pair modejabel — {IM_TEXT, "Draw a" }; 
void modo_j)roc(); 

caddr_t labeUtem; 

struct typed_pair namejabel »■ 

{IM_TEXT, "Left paints, Middle erases " }; 

caddr_t quitjtem; 

struct typed_pair quitjabel ■■ {IM_TEXT, "Quit* }; 

void quit_proc(); 

caddr_t load^item; 

struct typed_pair loadjabel = {IM_TEXT, "Load" }| 
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void load_proc(); 

caddr_t storejtem; 

struct typed_pair 8tore_label ™ {IM_TBIXT, "Store” }; 

void store_proc(); 

caddr_t fnamejtera; 

struct typed_pair file_label =• {IM_TEXT, "File” }; 

caddr^t fiUJtem; 

struct typed_pair filljabel {IM_TEIXT, "Fill" }; 

void filLproc(); 

caddr_t fiil_valuejteni; 

struct typed_pair fill_valuejabel {IM_TEXT, "with” }; 

void fUl_value_proc(); 

caddr_t invertjtem; 

struct typed_pair invertjabel — {IMLTEXT, "Invert* }; 
void invert_proc(); 

caddr_t flll_op_itenij 

struct typed_pair flll_op_Jabel {IM_TBXT, "Load / Fill should" }; 
void flll_op_proe(); 

caddr_t paint_op_item; 

struct typed_pair paint_op_|abeI “ {IM_TEXT, "Cursor op" }; 

void paint_op_proc(); 

int paint_op_removed — FALSE; 

caddr_t bkgmd_valuejtem; 

struct typedjjair bksmd_valuejabel * {IMJTEXT, "Proof background* }; 

•/ 

/• paint ops */ 

/* load / fill ops •/ 

/* codes •/ 
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void bkgrnd_proe(); 

/• Values for enums above 

#deftne OP_OR 0 
#deflne OPJCOR 1 

#deflne OPJIEPLAOE 0 

#define OP_MERGE 1 

#deflne GR JVHITE 0 

#deflne GR_GRAY25 1 

#deflne GRJIOOT.GRAY 2 
#deflne GR_GRAY50 3 

#defiDe GR_GRAY78 4 

#define GR_RLACK 5 

void 

mode_proe(optsw, ip, val) 
caddr_t optsw; 

caddr_t ip; 

ujnt val; 

{ 

set_^ate(val); 

} 

#define ICJMODECOUNT 2 
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char *mode_values[IC_MODECOUNT+1] =■ { "Cursor”,’Icon" }; 

struct typed_pair mode_choice8 “ {IM_TEiXTVEC, (caddr_t)mode_value8 }; 

#define IC.GRAYCOUNT 6 

char *gray_values[IC_GRAYCOUNT+ Ij =■ { 

"White”, ”25%”, "Root Gray”, ”50%”, ”75%”, "Black” }; 
struct typed_pair gray_choiees =“ {IM_TEIXTVEC, (caddr_t)gray_values }; 

#define ICJ'OPCOUNT 2 

char •fill_op_values[ICJF'OPCOUNT+ Ij — { "Replace”, "Merge” }; 

struct typed_pair fiH_op_choice8 " {IM_TEXTVEC, (caddr_t)fill_op_value8 }; 

fdeflne IC_POPCOUNT 2 

char .paint_op_values[IO_POPCOUNT+ l) - { "OR”, "XOR” }; 

struct typed_pwr paint_op_choices “ {IM_TEXTVEC, (caddr_t)paint_op_valuea }; 


f* general globals •/ 

int errno; 

static u_int cur_^, cur_y, 
cur_op, 
cell_count, 
celljize, 

state ■■ -1; /• *o first 8et_atate really does */ 

char file_default[] — "test.icon”; 

char file_name[1024]; 

struct pixfont *font; 

FILE esysout -■ stderr; 

main(argc,argv) 
int argc; 
char **argv; 

tool ■■ tool_create(tool_narae, TOOLJ'IAMESTRIPE, NULL, &my_icon); 
font -■ pf_default(); 

meg_svr «■ meg8w_createtoolsubwindovf(tool, ””, -1, MSG_IIEIGHT, font); 
mew — (struct megcub window *)mBg_8w*>t8_data; 

proofjsw ■■ tool_create8ubwindow(tool, PROOF_SIDE, PROOF_SIDE); 
init_proof(); 

optionsjsw —i optsw_createtoolsubwindow(tool,-1, OPTIONSJHEIGHT); 
init_option8(); 

canva8_8w ■■ tool_create8ubwindow(tool, -1, CANVASJSIDE); 
init_canva8(); 

fix_tool_rect(); 

set_state(OURSOR); 

filLvalue_proc(NULL, NULL, GRJtOOT.GRAY); 
bkgrnd_proc(NULL, NULL, GR_ROOT_GRAY); 
signal(SIGWINCH, sigwinched); 
tool_install(tool); 
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toolj9elect(tool, 0); 

tool_destroy (tool); 
exit(O); 


fix_tool_reet() 

if (wmgrj5windowopen(tool->tLwindowfd)) { 

win_getrect(tool->tl_windowfd, &tool_rect)i 
} else { 

win_getsavedrect(tool- > tl_windowfd, &tool_rect); 

tooL/ect.r_width — 2*tool_borderwidth(tool) + 

max(PROOF_SIDE + optsw_eoltox{osw, 64) + 
tool_8ubwindowspacing(tool), 

CANVAS.SIDE); 

tool_yect.r_height«“ MSGJIEIGHT 

+ CANVAS^SIDE + PROOF JSIDE 

+ tooLl!tripeheight(tool) 

+ tool_borderwidth(tool) 

+ 2*tool_8ubwindow8p8cing(tool); 
if (rect_bottom(&tool_reet) >" 800) { 

tool_reet.r_top rect_bottoni(&tool_fect) - 799; 

if (wingr_i8windowopen(tool->ti_windowfd)) { 

win_petreet(tool- >tl_windowfd, &tool_fect); 

} else { 

winj!et8avedrect(tool- >tl_windowfd, &toolject); 

} 

} 


8etj9tate(whieh) 

if (state «• which) { 
return; 

if ((state — which) CURSOR) { 
canvas_pr ■■ &new_eur8or_pr; 
cell_pize ■■ OURSOR^SIZE; 
if (paint_op_removed) { 

optBW_restoreitem8(oaw, paint_opJtem, 1, TRUE); 
paint opjretnoved « FALSE; 

} 

} else { 

canvas_pr ~ &icon_pr; 
celLsise " IOON_SIZE; 
if (!paint„op_yemoved) { 

optaw_removeitem8(osw, paint_op_itenj, 1, TRUE); 
paint_opj'emoved “ TRUE; 

} 


opts'w_8etvalue(osw, inodejtem, which); 
set^cursorO; 

ceU_Jount — CANVASJ>ISPLAY / ceU_sjze; 

paint_pToof(); 

paint^canvasO; 
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} 

set cursor() 

{ 

if (state == ICONIC) { 

win_setcursor(proof_pw->ts_windowfd, &main_cursor); 

} els* { 

win_setcur6or(proof_|5w- > ts_windowfd, &new_cursor); 

} 

} 

static 

sigwinehedO 

{ 

tooljBigwinch(tool); 

} 

nullprocO 

{ 

return; 

} 



int (*8aved_handler](); 
int saved.mask; 
int clear_me88age(); 

bitch(format, argl, arg2, arg3, arg4, argS, arg6, arg7, argS) 

char *format, *argl, *arg2, *arg3, *arg4, *arg5, *arg5, *arg7, *arg8; 

{ 

char buf[250]; 

8printf(buf,format, argl, arg2, arg3, 8rg4, argS, argS, arg7, argS); 
m8g!w_8et8tring(m8W, buf); 
aaved.mask — tool>>tUo.tio_inputmask; 
tool->tlJo.tioJnputma8k =■(!<< tool->tl_windowfd) + 

(1 << eanva8_8w->t8_windowfd) + 

(1 << option8_pw->t8_windowfd); 
if (toob>tl_io.tio_8elected 1™ ctear^essage) { 
saved3andler ■■ tooU>tI_io.tio_8eteet«d; 

tool->tI_}o.tio_8elected " clear_me88sge; 

} 

clear_inessage(datum, ibits, obits, ebita, timer) 
caddr_t datum; 

ujnt eibits, eobita, sebits; 

struct timeval **timer; 

{ 

msgsw_set8tring(msw, ””); 
tool->tl_io.tio_8elected "» saved_handler; 
tool->tl_io.tio_inputma8k “ 8avcd_mask; 

} 

/• 

• Proof Section 

•/ 

init_proof() 
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struct inputmask mask; 

inputJmnuU{&mask); , 

win^tinputmaak(proof_pw->ts_windowrd, &mask, NULL, WIN_NULLLINK); 
proQf^w->t8jo.tio3audlesigwinch — proof_pighandler; 
pro 9 f_pw->ts_de 8 troy ■— nullproc; 
proof ji* win "• pw_open(proof_pw->ta_windowfd); 

> 

static 

proof_8ighandler(8w_data) 
caddr.t Bw_data; 

p w_^amaged(proof_pLx win); 
pain^roof(); 

p w_di>nedama 5 ed(proor_pix win); 

proofjw->t8_width — win_getwidth(proof_pw->t8_windowfd); 
proof^w->t8jieight — win^etheight(proorj!w->t8_windowfd); 

} 

paint^proof^ 

mt X, y; 

for (y 0; y < proofj8w->tsJieight; y + — 64) { 

, for (x -» 0; X < proorjiw->ts_widtli; x + — 64) { 
pw_write(proof_pixwin, x, y, 84, 64, 

PDC.SR0, prootj)r, 0, 0); 

} 

If (stu^e —ICONIC) { 

paint_proofJcon(); 

) 


paint_proofjeon() 

^ pw.write(proof_pixwin, PROOF_MARGIN. PROOPJdARGIN, 84, 64, 
PDL3RC, &icon_pr, 0,0); 

} 


• Options subwindow section 

*/ 

init_optione{) 

^ win_seteuT8or(options_sw->t8_windowfd, 45main_cursor); 

08 w ■■ option8jiw->t8_data; 

modsjtem « opt8w_enum(o8w, &mode_l8bel, &mode_choice8, 
0, CURSOR, mode_proc); 
start_new_Jine(mode_item); 

labeljtem — optswJabel(osw, &namejabel); 

quitjtem “ optsw_command(osw, fequitjabel, quit_proc); 
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load_jtem — optsw_command(osw, &load_labe!, load_proc); 
start_newJine(loadJtem); 

storejtem — optsw_command(o8w, &store_labcl, store_proc); 

fnamejtem >=• opt8w_text(o3w, i:file_label, file_default, 0, NULL); 

fill_Jtem «■ opt8w_command(osw, &filU3'bel, f5il_proc); 
start_new_jine(filljtem); 

f511_valuejtem — optsw_enum(oBW, &fill_valuejabe!, 

&gray_choices, 

0, 2, fill_value_proc): 

invert_item ™ opt8w_command(o8W, &invert_label, invert_proc); 

fill_op_item optsw_enum{o8w, &fill_op_labe!, 

&flll_op_choice8, 

0, 0, NULL): 

start_newJine(fill_opJtem); 

paint_op_jtem ■■ optsw_enum(osw, &paint_op_lBbel, 

&paint_op_choice8, 

0, 1, paint_op_proc); 

bkgrnd_vBlue_item ■“ opt8w_enuni(osw, &bkgrnd_value_labe!, 

&gTay_choiee8, 

0, 2, bkgmd_proc); 
8 tart_newjline(bk 5 rnd_value_item); 

} 

8tart_new_line(item) /* special-ea8e routine for legibility •/ 

caddr.t item; 

{ 

struct item_place p; 

rect_conslruct(&;p.rect, 0, -1, -1, -1); 
p.flxed.x TRUE; 

p.flxed.y — p.flxed.w -■ p.fixed.h " FALSE; 
optsw setplace(osw, item, Sip, 0); 

} 

/* handlers for the various option items, in their creation order •/ 
void 

quit_proc(optsw, ip) 
caddr_t optsw; 

caddr_t ip; 

{ 

msgsw_set8tring(insw, 

"Please confirm with the left mouse button, or cancel with right or middle.”); 
if (cur8or_eonfirm(canvas_sw->ts_windowfd)) { 
tool_done(tool); 

} else { 

bitch(”Quit cancelled."); 

} 

} 

void 
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loacLproe(opt8w, ip) 
cnddr.t optsw; 

enddr_t ip; 

{ 

int e; 

u_int count, data[256], •dp, result; 

u_int op, mode, chunks; 

#define SHORT.CHUNKS 2 
fdefine LONG.CHUNKS 1 

struct striny. buf file_n&me_buf; 

FILE 'fd; 


filejo&me.buMimit •• 1024; 
file_nnniejbuf.deta <•■ file_nsme; 
result opt8w_getvslue(fnune_item, &file_nune_buf); 
if (result < 0) { 

biteh(”Trouble: icontool couldn’t rend the filename”); 

eleep(lO); 

exit(-l); 

fd •• fopen(flle_name, *r"); 
if(fd —NULL){ 

bitch(* Sorry, couldn’t open %8”, file_name); 
return; 

while ((e— getc(fd)) ’{’) { /* matching } •/ 

if(e--EOF) { 

bitch(” Sorry, I need an array of shorts or unsigneds”); 
return; 

} 

} 

dp V data; 
count ~0; 

do { result — fseanf(fd, " 0x%X,”. dp+ +); 
counts +; 

} while (result — 1); 
felose(fd); 

switch (-count) { 


case 8; 

mode « CURSOR; 
chunks - LONO_OHUNKS; 
break; 

case 10: 

mode « CURSOR; 

chunks - SHORT.CHUNKS; 

break; 

case 128: 

mode B ICONIC; 

chunks - LONO.CHUNKS; 

break; 

ease 250: 

mode - ICONIC; 

chunks - SHORT.CHUNKS; 

break; 

default: 

bitch(”Sorry, I don’t understand that array.” 
return; 


op ■■ optew_getvalue(fill_opJtem, &resuit); 
if (mode CURSOR) { 

dp « new^cursor.anay; 

} else { 

dp V iconjarray; 
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if (chunks — LONG.CHUNKS) { 
if (op OPJIEPLACE) { 

replace_longs(dp, data, count); 

} else { 

merge long8(dp, data, count); 

} 

^ else ^ 

if (op — OP_BEPLACE) { 

replacejshorts(dp, data, count); 
} else { 

merge shorts(dp, data, count); 

} 

} 

state ■■ -1; 
set_Btate(mode]; 



static 

replace_longs(target, source, count) 
int ‘target, ‘source, count; 


{ 

} 


while (count- > 0) { 

target[countj " source|countJ; 

} 


static 

merge_longs(target, source, count) 
int ‘target, ‘source, count; 


{ 

} 


while (count— > 0) { 

target[count] source|eount]; 

} 



static 

replace_3borts(target, source, count) 
int ‘target, ‘source, count; 

{ 

while (count— > 0) { 

target (count/2] “ source[countj; 
target(eount/2j (■■ (sourcejcount-1) << 16); 
count -■■1; 

} 

} 


static 

merge_8horts(target, source, count) 
int ‘target, ‘source, count; 

{ 

while (count- > 0) { 

target|count/2j |” sourcejeount); 
targetjcount/2| (souree(count-l| << 16); 
count -«a« 1; 

} 

} 


void 
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store_p70c(opt8w, ip) 
caddr_t optsw; 

caddr^t ip; 

{ 

int 

u_int 

char 

struct 8trins_buf 

FILE 
struct stat 


i, limit, result, size; 
•data; 

•token; 

file^pame buf; 

•fd; 

8tat_buf; 


file_name_buf.limit 1024; 
file_name_buf.data file.name; 
if (state — CURSOR) { 
size B 10; 

data B new_cursor_array; 
token B "cursor"; 

} else { 

size B 64; 
data B icon^array; 
token B "icon"; 

} 

result B optsw_getvalue(fnzune_item, AflIe_namo_buf); 
if (8tat(file_name, Isstat.buf) bb -1) ( 
if (errno 1—ENOENT) { 

bitch(” Sorry, %s”, 8yB_errlist[enno)); 
return; 

} 

} else { /• stat succeeded; file exists •/ 

bitch(”%8 exists; please confirm overwrite.”, filejname); 
if (lcureor_conflrm(canva8_8W*>te_windowfd)) { 
return; 

> 

} 

fd b fopen(flle^ame, ”w”); 
if(fdBBNULL] { 

bitch("Sorry, can’t write to %s", file.name); 
return; 

} 

fpnntf(fd, ”\n8tatic un8igned%8_data(%d| b (\n*, 
token, siie * size / 32); 

limit B size * sise / 128; 
for (ibO; i<Umit;) { 

fprintf(fd, "0x%-08X, 0x%-08X, 0x%-08X, Ox%-08X', 
data(0], data(l], data|2|, dsta(3]); 
data + B 4; 
if (+ + i < limit) { 

fput8(”,\n”, fd); 

} 

} 

fput8(”\n};\n”, fd); 
fclo8e(fd); 


void 

fillj)roc(op tew, ip, val) 

{ 





Revision D pf 7 January 1084 


B-21 




Sample Tools 


Sun Windows Reference Manual 


int op, X, y, result; 

switch (opt5W_getvalue(filLopJtem, feresult)) { 
case OPJtEPLACE: op = PDCSRC; break; 

case OP_MERGE: op =« PIX-SRC | PIXJ5ST; break; 
default: bitch(" Trouble: fill doesn’t know what to do.”); 

for (y =i 0; y < eell_count; y + ™ 84) { 

for (x «• 0; X < cell_count; x + “ 84) { 

pr_rop(canva8_pr, x, y, cell_count, cell_count, 
op, filLpr, 0, 0): 

} 

} 

paint_canva8(); 
if (state “ ICONIC) { 
p«nt_proofjcon(); 

} else { 

6et_cursor(); 

} 

} 

void 

fiU_value_proc(opt8w, ip, val) 

{ 

switch (val) { 

case GR_WHITE: filLpr &whlte_patch| 

break; 

case GR_GRAY25: filLpr &gray25_patch; 

break; 

case GRJROOT_GRAY: flll_pr — &root_gray_patch; 

break; 

case GR_GRAYS0; finj>r — &gray50_pateh; 

break; 

case GR_GRAY75: flll_pr — &gray75_patch; 

break; 

ease GRJBLACK: fill_pr &black_patch; 

break; 

default: fill_pr — &root^ay_patch; 

} 

} 

void 

invert_proe() 

pr_rop(canvae_pr, 0, 0, ceIl_count, ceU_count, 
PDU^OT(PIXJ)ST), 0, 0, 0); 
paint eanvas(]; 
if (state — ICONIC) { 
paint_proofjcon(); 

} else { 

set cursor(]; 

} 

} 




void 

paint_opjroc(optsw, ip, val) 
caddr_t optsw; 

caddr_t ip; 

u_jnt val; 



B-22 


Revision D of 7 January 1084 







SunWindows Reference Manual 


Sample Tools 


{ 

u_int op; 

if (val — OPJCOR) { 

new_curBor.cur_function PDCSRC * PIXJ)ST; 

} else { 

new_cur8or.cur_function ■■ PDCSRC f PDC-PST; 

} 

set_cursor(); 

} 

void 

bkemd_proc(optsw, ip, val) 

{ 

switch (val) { 

case GR^WHITE: proof_pr — £:white_patch; 

break; 

case GR_GRAY25: proof_pr ■■ &gray25_pateh; 

break; 

case GR_ROOT_QRAY: proof_pr ■■ &root_gray_patch; 

break; 

case GR_GRAY50: proof_pr ™ &gray50_pateh; 

break; 

case GR_GRAY76: proof_pr — &grsy75_patch; 

break; 

case GR^LAOK: proof_pr —■ &black_patch; 

break; 

default: proof_pr = &root_gray_patch; 

} . 

paint_proof(); 

} 

/• 

e Canvas Section 

•/ 

init^canvasO 

{ 

struct inputmask mask; 

canvas.reader canvas.basereader; 
canva8_pixwin pw_open(eanva8_sw->ts_windowfd); 
canvas_BW->ts_io.tiojselected » canva8_8eleeted; 
canvaB_sw->t8jo.tio_handlesigwineh ■■ canva8_eighandler; 
canvas_aw->ts_deetroy ■■ nullproc; 

inputJmnull(&ma8k); 
wm.setinputeodebit(&ma8k, MSJLEFT ); 
win_setinputcodebjt(&mask, MS3flDDLE); 
win_setinputcodebit(&niask, LOC_MOVEWHILEBETDOWN); 
win_Betinputcodebit(&nissk, LOOJSTILL); 
win_8etiDputcodebit(&niask, LOG_WIN£inT); 
mask.im_}lag8 I"" IMJNEGEVENT; 

winj9etinputmask(canvas_sw->ts^windowfd, &mask, NIILL, WIN_NIILLLINK); 
win_8etcur8or(canvaiJ3W- > t8_windowfd, &mwn_cur8or); 
cur_;c ■■ cur_y ■■ -1; 

} 

static 
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canvas_selected{nullsw, ibits, obits, ebits, timer) 
caddr_t ‘nuUsw; 

int ‘ibits, ♦obits, *ebits; 

struct timeval ‘timer; 

{ 

struct inputevent ie; 

if (input_readevent(canvas_pw->ts_windo'wfd, &ie) -1) { 

perror(*icontool input failed”); 
abort(); 

} 

(*canvas_reader)(&ie); 

♦ibits ‘obits ■■ ‘ebits ^ 0; 

} 



static 

canvas3asereader(ie) 
struct inputevent ‘ie; 

if (winjnputnegevent(ie)) { 
return; 

} 

switch (ie->ie_code) { 
case MS_I/EFT: cur_op ■» 1; 

break; 

case MS_Mn)DLE: cur_op ™ 0; 
break; 

default: return; 

8 et_canva8_tracker(); 
eanva8_feedback(ie); 

} 

static 

eanvas_traeker(ie) 
struct inputevent ‘ie; 

if (winjnputnegevent(ie)) { 
switch {ie'>ie_code) { 
case 
ease 

reaet^eanvas_reader(); 

if (state — ICONIC) { 
paint_proof_icon(); 

} 

} 

return; 

> . . . 

switch (ie*>ie_code) { 

case LOC_WINEIXIT: reaet_canvas_reader(); 

if (state — ICONIC) { 
paint_proof_icon(); 

} 

return; 

case MS_LEFT: /‘ two buttons down? ‘/ 

case MS3®D0LE: cur_op «=■ -1; 

canvas_reader «• waitJega!_mou8e; 
return; 

case LOC_STILL: 


/• ignore all other input ‘/ 


/* mouse button up ‘/ 
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} 


case LOC_MOVEWHILEBUTDOWN: 

canva8_feedback(le); 

return; 

} /* ignore all other input •/ 


static 

waitjiegaljnousepe) 
struct inpuievent *ie; 

{ 

if (ifr>ie_code — LOC.WINEXIT) { 
reset_canvas_reader(); 
return; 

} 

if (winjnputnegevent(ie)) { 
switch (ie->ie_code) { 
case MSJLEFT: cur_op ■■ 0; 

break; 

ease MS.MIDDI'E: cur_op 1; 

break; 

default: return; 

} 

Bet_canva8_tracker(]; 

eanvas^eedbaek(ie); 

} 

} 


static 

8et_canvas.tracker() 

{ 

cur_;t ■■ cur_y ■■ -1; 
canvas^reader canvas.tracker; 

} 

static 

reBet_canva8.reader() 

{ 

canvas^eader »• canvas.basereader; 
cur_op ■■ -1; 

} 


static 

canvas_feedbaek(ie) 
struct inputevent *ie; 

{ 

register int new_g, new_y, color; 

if (ie<>ie_eode » LOOJSTILL &k state — ICONIC) { 
paint_proof_icon(); 
return; 

) 

if (ie->ieJocx < CANVAS_MARGIN || ie->ieJocy < CANVj^JMARGIN) { 
return; 

} 

new_;t (ie->ie_locx • CANVAS_MARGIN) / cell_swe; 

new_y " (ie->ie_loqr - CANVAS_MARGIN) / celljsise; 

if (newjt >* celUcount || new_y >— celLcount) { 
return; 

} 
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color — pr_get(canvas_pr, new_;t, new_y); 

if (new_;c — curj && new_y — cur_y && cur_op color) 
return; 

cur_x — new_^; 
cur_)r *= new_y; 
paint_cell(new_;c, new_y, cur_op); 
pr_put(canvas_pr, ne-w_x, new_y, cur_op); 
if (state CURSOR) { 

8 et_cur8or(); 

} 

} 

static 

canva8_8ighandler() 

P'w_damaged(csnv88jjix win); 
paint_canvas(); 

pw donedamaged(c8nvas_j)ixwin); 

} 

paint.canvasO 

{ 

register int x, y; 
struct rect r; 

pw writebackground(canva8_pixwin, 0, 0, BIG, BIO, PDC_CLR); 
r.r jefl - OANVASJVIARGIN; 
r.r_width ™ cell_count * celljsise; 
r.r_height — celLsize; 

pw_veetor(canva8_pixwin, CANVAS_MARGIN, CANVAS31ARGIN, 
rect_right(&r), CANVAS_MARGIN, 

PDeSET, 1); 

pw vector(canva8_pixwin, CANVAS_MARGIN, CANVASJMARGIN, 
CANVAS31ARGIN, rect_right(&r), 

PDeSBT, 1); 

for (y ■“ 0; y < cell_count; y+ +) { 

r.r_top ™ 0ANVAS,34ARGIN + celljiie • y; 

pw_Iock(canvas_pixwin, &r); 

for (x ™ 0; X < cell_eount| x+ + ) { 

»f (pr_get(canvaB_pr, x,y)) { 
paint_c«ll(x, y, 1); 

} 

} 1 

pw unlock(canva8_pixwin); 

} 

r.r.top - CANVASJvlARGINi 
r.r_width + “1; 

r.r_heisht ■■ cell_count • celljixe + 1; 
pw_loek(canva8_pixwin, &r); 

pw_vector(canva8_pixwin, rect_right(&r), CANVASJMARGIN, 
rect_right(&r), rect_bottonj(&r), 

PDC.SET, 1); 

pw_vector(canva3_pixwin, CANVAS3fARGlN, rect_bottom(&r), 
rect_right(&r), rect_bottora{&r), 

P1X.SET, 1); 

pw_unlock(canvas_pixwin); 

} 

p»nt_cell(x, y, color) 
int X, y, color; 

{ 



o 
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} 


register int dx, dy, dim; 

dx «■ CANVAS_MARGIN + celLsise^x + 1; 
dy - OANVAS3IARGIN + cell_sise*y + 1; 
dim « cell_^ixe -1; 

pw_write(eanvas_pixwin, dx, dy, dim, dim, PIX_SBC, 
(color ? £;graySO_patch : &white_j>atch), 1, 1); 
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Appendix C 


Sample Graphics Programs 


Use these sample programs as templates for your own graphics programs. Included is code for a 
bouncing ball demonstration {bouncedemo.c) and for a “movie camera" program {framedemo.c, 
which displays files sequentially like movie frames for producing a rotating globe for example. 
The source files for these and other graphics demos are found on f utrf auntoollsrcf *demo.c. 

C.l. bouncedemo.c Code 

Code for the bouncedemo.c follows. 

#ifndef lint 

static char sccaidO -■ ’'Q(#)bouncedemo.c 1.6 83/08/26 Sun Micro"; 

#endif 

/• 

* Sun Microsystems, Inc. 

•/ 

/• 

• Overview: Bouncing ball demo in window 

•/ 

^include <t!y8/types.h> 

^include "pixreet/pixrect.h” 

^include "sunwindow/rect.h* 

#include "sunwindow/rectlist.h" 

#include "sunwindow/pixwin.h” 

#include "euntool/gfxsw.b" 

main(argc, argv) 
int argc; 
char **argv; 

{ 

short X, y, vx, vy, s, ylastcount, ylast; 
short Xmax, Ymax, sue; 
struct rect rect; 

struct gfxsubwindow •gfx gfx8w_init(0, argv); 

Restart; 

win_getsise(gfx->|fx_windowfd, ftrect); 

Xmax « rect_right(&rect); 

Ymax ■■ rect_bottom(&rect}; 
if pQnax < Ymax) 


ai 
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size »■ Xmax/2il+ 1; 

else 

size “«Ymax/29+ 1; 
x—rect.rjeft; 
y«™rect.r_top; 

VX--4; 
vy—0; 
ylasti—0; 
ylastcount—0; 

pw_writebackground(gfx->gfx_pixwin, 0, 0, rect.r_width, rectrjieight, 

PDeSRO): 

while (gfx->gfx_reps) { 

if (gfx->gfxJlafs&GFX_PAMAGED) 
gfxswjiandlesigwinch(gfx); 
if (gfx->gfx_flags&GFXJlESTART) { 

gfx->gfx_flag8 &- 'GFXJIESTART; 
goto Restart; 

} 

if (y—ylast) { 

if (yla6tcount+ + > 6) 
goto Reset; 

} else { 

ylast — y; 
ylasteount " 0; 

> .... 

pw writebackground(gfx->gfx_pixwm, x, y, size, size, 

PIXJ^OT(PDCJ)ST)); 

xox-f vx; 

if (x>pCinax-size)) { 

/• 

* Bounce off the right edge 

*/ 

x“2»pCmax-size)-x; 
vx— -vx; 

} else if (x<reet.r_}eft) { 

/• 

* bounce off the left edge 

•/ 

X— -x; 

VXH -vx; 

} 

vy—vy+ 1; 
y—y+ vy; 

if (y>—(Ym ax-size)) { 

/• 

* bounce off the bottom edge 

•/ 

y—Ymax-size; 
if (vy<8ize) 

vy—1-vy; 
else 

vy—vy / rize - vy; 
if (vy-=0) 

goto Reset; 

) 

for (z=0; z<=‘1000; z+ +); 
continue; 

Reset: 

if (-gfx->gfx_reps <— 0) 
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break; 

x«rect.rjeft; 

y«irect.r_top; 

vx«-4; 

vy-0; 

ylast»“0; 

ylastcount=0; 

> 

gfxsw_done(gfx); 

) 


C.2. framedemo.c Code 

Code for the framedemo.e follows. 

){(ifndef lint 

static char sccsidQ "®( 5 jl)framedemo.c 1.10 84/01/11 SMP; 
#endif 

/* 

* Sun Microsystems, Inc. 

•/ 

/• 

0 

0 

0 

O 

#include <Btdio.h> 

^include <8ys/typeB.b> 
ijtinclude <sy8/file.h> 

#include <8y8/time.h> 
li^include "pixrect/pixreet.h” 
tjtinelude ”pixreet/pr_util.h" 

^include ’’pixrect/bwlvar.h” 
tjlinclude ’’pixrect/memvar.h” 

^include "sunwindow/rect.h" 

^include ’’sunwindow/reetlist.h” 

#include "sunwindow/pixwin.h” 

#include "sunwindow/winjnput.h" 

#inelude "Bunwindow/winjitruet.h” 

#inelude "sutttool/gfxsw.h” 

#deiine MAXFRAMES 1000 

#deiine FRAMEWIDTH .250 

#dei!ne FRAMEHEIOHT 250 

#define USECJNC 60000 

#deflne SEOJNO 1 

static struct pixrect »mpr[MAXFRAMESl; 
static struct timeval timeout ™ {SEJCJNO,USECJNC}, timeleft; 
static char sj] •a ” frame.xxx”; 
static struct gfxsubwindow *gfx; 
static int frames, framenum, ximage, yimage; 
static struct rect rect; 



Overview; Frame displayer in windows. Reads in all the 

flies of form "frame.xxx* in working directory & 
displays them like a movie. 

See constants below for limits. 
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mMn(arge, argv) 
bt argc; 
char **argv; 

mt fd, framedemo_seIected(]; 
struct inputmask im; 

for (frames 0; frames < MAXFRAMES; frame3+ + ) { 

8printf(&sl8), "%d", frames + 1); 
fd " open(e, 0_PD0NLY, 0); 
if (fd >1) { 
break; 

mprlframes] ■■ mem_ereate(FRAMEWIDTH, FRAMEIHEIGHT, 1); 
read(fd, mpr_d(mpr(framesl)- > md Jm age, 
FRAMEWroTH*FRAMEHEIGHT/8); 
close(fd); 

} 

if (frames 0) { 

printfC Couldn’t find any ’frame.xx’ files in working directoryXn”); 
return; 

} 

/• 

* Initialise gfxsw ("take over” kbd) 

•/ 

gfx — gfxsw_init(0, argv); 

/• 

* Set up input mask 

*/ 

inputjmnull(&im); 
im.imjfiags |«« IMLASCH; 

gfx8W_setinputmask(gfx, &im, &im, W1N_NULLLINK, 1, 0); 

/• 

« Main loop 

*/ 

framedemojnextfrsme(l); 
timeleft ■■ timeout; 

gfxswjselect(gfx, framedemo_seleeted, 0, 0, 0, &timeleft); 

/• 

* Cleanup 

*/ 

gfxsw_done(gfx); 

framedemo_seIected(gfx, ibits, obits, ebits, timer) 
struct gfxsubwindow *gfx; 
int *ibits, *obite, *ebits; 
struct timeval *• timer; 

if ((*timer && ((‘timer)->tv_8ee 0) && ((•timer)->tv_uBee 0)) ]| 

(gfx.>gfxjlags & GFXJRESTART)) { 

/• 

• Our timer expired or restart is true so show next frame 

•/ 

if (gfx->gfx_reps) 

framedemo_pextframe(0); 

else 

gfx 8w_selectdone(gfx); 

} 

if (‘ibits & (1 << gfx->gfx_windowfd)) { 





C-4 


Revision D of 7 January 1S84 









SunWindows Reference Manual 


Sample Graphics Programs 


struct inputevent event; 


* Read input from window 

•/ 

If (input_readevent(gfx->gfx_windowfd, &eyent)) { 
perror(* framedemo”); 
return; 

} 

switch (event. ie_code) { 

ease T; /• faster usee timeout */ 

if (timeout.tv_usec >— USECJNC) 
timeout.tv_u8ee USEOJNO; 

else { 

if (timeout.tv_pec >«« SECJNC) { 
tiraeout.tv_8ee SEOJNC; 
timeout. tv_usee lOOOOOO-USEOJNC; 

} 

} 

break; 

case ’s’: /• slower usee timeout */ 

if (timeout.tv_usee < 1000000-USECJNC) 
timeout.tv_u8ec + — USEOJNO; 

else { 

timeout.tv_u6ee — 0; 
timeout.tv^see ~ 1; 

} 

break; 

case ’F’; /* faster see timeout */ 

if (timeout.tv^see >■■ SEOJNO) 
timeout.tv^eee — SEOJNO; 

break; 

ease ’S’: f* slower see timeout */ 

timeout.tvjiee + ■■ SEOJNO; 
break; 

case ’f’: /• Help •/ 

printfC's’ slower usee timeout\n’r faster usee timeout\n’S’ slower sec timeout\n'F’ faster sec timeoutVn”); 

/• 

* Don’t reset timeout 

•/ 

return; 

default: 

gfxswjnputinterrupt8(gfx, &event); 

} 

} 

*iblts *obits ■■ sebits ■■ 0; 
timeleft ■■ timeout; 
etimer ■■ £timeleft; 

} 

fraroedemo_nex tframe(fir8ttime) 
int firsttime; 

int restarting » gfx'>gfx_flsgs&GFNJlESTART; 

if (firsttime || restarting) { 

gfx*>sfx_flag8 'GFXJIESTART; 
win_getsise(gfx->gfx_windowfd, &rect); 
ximage » reet.r_width/2-FRAMEWIDTH/2; 
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yimage •= rect.r_hciKht/2-FRAMEHEIGHT/2; 
pw_writebackground(gfx->gfx_pixwin, 0, 0, 
rect.r_width, rect.r_}»«iKf>ti PIX_CLR)) 

if (framenum >-• frames) { 
frame num — 0; 
gfx->gfxjrep8-; 

pw_write(gfx->gfx_pixwin, ximage, yimage, FRAMEWIDTH, FRAMEHEIGHT, 
PIX_£KC, mpr|framenuml, 0, 0)j 
if (I restarting) 

frameiium+ +; 
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Here are usefvil hints for programmers who use any of the pixrect, sunwindow or euntool 
libraries. 

D.l. What Li Supported? 

In each release, there may be some difference between the documentation and the actual pro¬ 
duct implementation. The documentation describes the supported implementation. In general, 
the documentation indicates where features are only partially implemented, and in which direc¬ 
tions future extensions may be expected. Any necessary modifications to SunWindows are 
accompanied by a description of the nature of the changes and appropriate responses to them. 

D.2. Program By Example 

We recommend that yon try to program by example whenever possible. Take an existing pro¬ 
gram similar to what you need and modify it. Appendix B contains some sample tools and 
Appendix C contains some sample graphics programs. The source for these and other sample 
tools and graphics programs are available on f uirf suntoolf arcf *.e. 

D.3. Header Files Needed 

If you have problems finding the necessary header files for compiling your program, using the 
examples may help as many of the header files are already included. Moreover, there are certain 
header files that include most of the header files necessary for working at a certain level. The 
following table shows these header files: 
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Table D-1: Header Files Required 


Use 


When Working at the Level of 


/usr/ificludejsuntoolj tool_h».h 


I u»rf include! tuntoolj gjxjit.k 


/ utrj include! eunmndowj mndow_h*.h 


!uar! include! pixrect! pixrectjkt.h 


suntool tool-building facilities; includes headers 
needed to work at the more primitive layers as well 

the suntool (standalone or “take over”) graphics 
subwindow facilities; includes headers needed to 
work at the more primitive layers as well 

sunwindow basic window facilities layer; includes 
headers needed to work at the pixrect layer as well 

pixrect display primitives layer _ 


Include only one of the above header files plus whatever extra header files you need. In particu¬ 
lar, you’ll need to aidd the header file for each subwindow type that you use, the menu header 
file if you use menus, the sel^tion header file if you are going to use selections, and so on. How¬ 
ever, you’ll probably only have to add a single header file for each additional increment of high- 
level functionality. 


D.4. Lint Libraries 

Sun^^^ndows provides /int librariea to help you run lint over your program source. Lint catches 
argument mismatches and provides better type-checking than the C compiler. Llib-lpizrect, 
llib‘UunufindovD, and llib-Uuntool are the source files to make the actual binary ftnt(l) libraries: 
llib-lpixreet.ln, llib~Uunwindow.ln, and llib-l»untooUn, These files are found on !usr!lib)lint!. 


D.5. Library Loading Order 

When loading programs, remember to load higher level libraries first, that is, -leuntool -ilsunuun- 
dow Apizrect. 

D.6. Shared Text 

The tools released with auntooU rely on text sharing to reduce the memory working set. This is 
accomplished by placing the entire collection of tools in a single object file. This has the effect 
of letting each separate process share the same object code in memory. With many windows 
active at once this can achieve significant memory savings. 

There are trade-offe using this approach. The main one is that the maximum number of per- 
process and non-sharable initial data pages tends to be larger. However, the paged virtual 
memory tends to reduce the effect of this by only having the working set paged in. 

The upshot of this is that you may want to either add the tools that you create to the released 
shared object file or to bundle a few tools together into their own object file. 
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D.7. Error Message Decoding 

The default error reporting scheme described at the end of Window Manipulation displays a long 
hex number which is the ioetl number associated with the error. You can turn this number into 
a more meaningful operation name by: 

• turning the two least significant digits into a decimal number; 

• searching f turf includejsunwindowfwin_ioctl.h tor occurrences of this number; and 

• noting the ioetl operation associated with this number. 

This can provides a quick hint as to what is being complained about without resorting to a 
debugger. 

D.6. Debugging Hints 

When debugging non-terminal oriented programs in the window system, there are some things 
that you should know to make things easier. 

As discussed in the section entitled Overlapped Windows: Imaging Facilities - Damage, a process 
receives a SIOWINCH whenever one of its windows changes state. In particular, as soon as a tool 
issues a tooljinstall, the kernel sends it a SIGWINCH. When running as the child of a debugger, 
the SIGWINCH is sent to the parent debugger instead of to the tool. By default, dbx simply pro¬ 
pagates the SIGWINCH to the tool, while adb traps, leaving the tool suspended until the user con¬ 
tinues from adb. This behavior is not peculiar to SIGWINCH: adb traps all signals by default, 
while dbz has an initial list of signals (including SIGWINCH) that are passed on to the child pro¬ 
cess. You can instruct adb to pass SIGWINCH on to the child process by typing lc:i followed by 
RETURN. ‘Ic* is the hex number for 28, which is SIGWINCH’s number. Re-enable signal breaking 
by typing lc:t followed by RETURN. You can instruct dbz to trap on a signal by using the catch 
command. 

For further details, see the entries for the individual debuggers in the User's Manual for the Sun 
Workstation. In addition, ptraee(2) describes the fine points of how kernel signal delivery is 
modified while a program is being debugged. 

The two debuggers differ also in their abilities to interrupt programs built using tool windows. 
Dbz knows how to do interrupt these programs, but adb doesn't. See Signals from the Control 
Terminal below for an explanation. 

Another situation specific to the window system is that various forms of locking are done that 
can get in the way of smooth debug^ng while working at low levels of the system. There are 
variables in the sunwindow library that disable the actual locking. These variables can be 
turned on from a debugger: 
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Table D-2: aununndotp Variables for Disabling Locking 


Variable 

Action 

int pizwindebug 

When not zero this causes the immediate release of the 
display lock after locking so that the debugger is not con¬ 
tinually getting hung by being blocked on writes to screen. 
Display garbage can result because of this action. 

int u>in_lockdatadebug 

When not zero, the data lock is never actually locked, 
preventing the debugger from being continually hung due 
to block writes to the screen. Unpredictable things may 
result because of this action that can’t properly be 
described in this context. 

int u>in_grabiodebug 

When not zero will not actually acquire exclusive I/O ac¬ 
cess rights so that the debugger wouldn’t get hung by be¬ 
ing blocked on writes to the screen and not be able to re¬ 
ceive input. The debugged process will only be able to do 
normal display locking and be able to get input only in the 
normal way. 

int fullscreendebug 

Like u)in_gfabiodebug but applies to the fullscreen access 
package. 


Change these variables only during debugging. You can set them anytime after main has been 
called. 


D.9. Sufficient User Memory 

To use the e untool environment comfortably requires adequate user memory for SunWindows 
and the Sun UNIX operating system. To achieve the best performance, reconfigure your own 
kernel, deleting unused device drivers. The procedure is documented in the System Manager's 
Manual for the Sun Workstation. For a workstation on the network with a single disk drive, 
you will be able to reclaim significant usable memory. 

For the recommended amount of memory, see the Sun Workstation Configuration Guide. 


D.IO. Coexisting with UNIX 

This section discusses how a SunWindows tool interacts with traditional UNIX features in the 
areas of process groups, signal handling, job control and terminal emulation. If you are not 
familiar with these concepts, read the appropriate i>ortions {Process Groups, Signals) of the Sys¬ 
tem Interface Overview and the siynaf(3) and «y(4) entries in the System Interface Manual for 
the Sun Workstation . 

This discussion explicitly notes those places where the shells and debuggers interact differently 
with a tool. 
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D.10.1. Tool Initialization and Process Groups 

Systesn calls made by the library code in a tool affect the signals that 'will be sent to the tool. A 
tool acts like any program when first started: it inherits the process group and control terminal 
group from its parent process. However, when a tool calls tool_create, tool_ereate changes the 
tool's process group to its own process number. The following sections describe the effects of 
this change. 

D.10.1.1. Signals from the Control Terminal 

When the C*Shell (see csh(l)) starts a program, it changes the process group of the child to the 
child's process number. In addition, if that program is started in the foreground, the C-Shell 
also modifies the process group of the control terminal to match the child’s new process group. 
Thus, if the tool was started from the C>Shell, the process group modification done by 
tooi_create has no effect. 

The Bourne Shell (see sA(l)) and the standard debuggers do not modify their child’s process and 
control terminal groups. Furthermore, both the Bourne Shell and <idfr(l) are ill-prepared for the 
child to perform such modification. They do not propagate signals such as SIGINT to the child 
because they assume that the child is in the same control terminal group as they are. The 
bottom-line is that when a tool is executed by such a parent, typing interrupt characters at the 
parent process does not affect the child, and vice versa. For example, if the user types an inter¬ 
rupt character at (^db while it is debugging a tool, the tool is not interrupted. Although dbx{l) 
does not modify itB child’s process group, it is prepared for the child to do so. 

D.iO.i.2. Job Control and the C-Shell 

The terminal driver and C-Shell job control interact differently with tools. First, let us examine 
what happens to programs using the graphics subwindow library package. When the user types 
an interrupt character on the control terminal, a signal is sent to the executing program. Often 
the signal is a SIGTSTP. The sfxaw library code sees this signal and tidies up by releasing any 
SunWindows locks that it might have and by removing the graphics from the screen before it 
actually suspends the program. If the program is later continued, the graphics are restored to 
the screen. 

However, when the user types the C-Shell’s stop command to interrupt the executing program, 
the C-Shell sends a SIGSTOP to the program and the gfxsw library code has no chance to clean 
up. This causes problems when the code has acquired any of the SunWindows locks, as there is 
no opportunity to release them. Depending on the lock timeouts, the kernel will eventually 
break the locks, but until then, the entire screen is unavailable to other programs and the user. 
To avoid this problem, the user sends the C-Shell kiU command with the -TSTP option instead 
of using stop. 

The situation for tools parallels that of the gfxsw code. Thus a tool that wants to interact nicely 
with job control must receive the signals related to job control (siGlNT, SIGQUIT, and SIGTSTP) 
and release any locks it has acquired. If the tool is later continued, the tool must receive a 
SIQCONT so that it can reacquire the locks before resuming the window operations it was exe¬ 
cuting. The tool will still be susceptible to the same problems as the gfxsw code when it is sent a 
SIGSTOP, 

A final note: the user often relies on job control without realizing it; the expectation is that typ¬ 
ing interrupt characters will halt a program. Of course, even programs that do not use 
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SunWindows facilities, such as a program that opens the terminal in "raw” mode, have to pro¬ 
vide a way to terminate the program. A program using the gfx«v> package that reads any input 
can provide limited job control by calling gflMULinputmterrupfr. 
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